Skip to content

Commit c0f3022

Browse files
masatakemasatake
committed
KernelDoc: new parser
This one is disabled by default. Give --languages=+KernelDoc for enabling. Signed-off-by: Masatake YAMATO <[email protected]>
1 parent 0a045aa commit c0f3022

File tree

17 files changed

+597
-30
lines changed

17 files changed

+597
-30
lines changed

‎Tmain/list-subparsers-all.d/stdout-expected.txt

Lines changed: 31 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,31 @@
1-
#NAME BASEPARSER DIRECTIONS
2-
AnsiblePlaybook Yaml base <> sub {bidirectional}
3-
Ant XML base <> sub {bidirectional}
4-
Autoconf M4 base <> sub {bidirectional}
5-
Automake Make base <= sub {dedicated}
6-
Bats Sh base <= sub {dedicated}
7-
DBusIntrospect XML base <> sub {bidirectional}
8-
FunctionParameters Perl base <> sub {bidirectional}
9-
GemSpec Ruby base <= sub {dedicated}
10-
Glade XML base <> sub {bidirectional}
11-
IPythonCell Python base => sub {shared}
12-
ITcl Tcl base <> sub {bidirectional}
13-
Maven2 XML base <> sub {bidirectional}
14-
Moose Perl base <> sub {bidirectional}
15-
OpenAPI Yaml base <> sub {bidirectional}
16-
PlistXML XML base <> sub {bidirectional}
17-
PythonLoggingConfig Iniconf base <> sub {bidirectional}
18-
QtMoc C++ base <> sub {bidirectional}
19-
R6Class R base <> sub {bidirectional}
20-
RMarkdown Markdown base <= sub {dedicated}
21-
RSpec Ruby base => sub {shared}
22-
Rake Ruby base <= sub {dedicated}
23-
RelaxNG XML base <> sub {bidirectional}
24-
S4Class R base <> sub {bidirectional}
25-
SVG XML base <> sub {bidirectional}
26-
SystemdUnit Iniconf base <= sub {dedicated}
27-
TclOO Tcl base <> sub {bidirectional}
28-
TeXBeamer Tex base <> sub {bidirectional}
29-
XSLT XML base <> sub {bidirectional}
30-
YumRepo Iniconf base <= sub {dedicated}
1+
#NAME BASEPARSER DIRECTIONS
2+
AnsiblePlaybook Yaml base <> sub {bidirectional}
3+
Ant XML base <> sub {bidirectional}
4+
Autoconf M4 base <> sub {bidirectional}
5+
Automake Make base <= sub {dedicated}
6+
Bats Sh base <= sub {dedicated}
7+
DBusIntrospect XML base <> sub {bidirectional}
8+
FunctionParameters Perl base <> sub {bidirectional}
9+
GemSpec Ruby base <= sub {dedicated}
10+
Glade XML base <> sub {bidirectional}
11+
IPythonCell Python base => sub {shared}
12+
ITcl Tcl base <> sub {bidirectional}
13+
KernelDoc CPreProcessor base => sub {shared}
14+
Maven2 XML base <> sub {bidirectional}
15+
Moose Perl base <> sub {bidirectional}
16+
OpenAPI Yaml base <> sub {bidirectional}
17+
PlistXML XML base <> sub {bidirectional}
18+
PythonLoggingConfig Iniconf base <> sub {bidirectional}
19+
QtMoc C++ base <> sub {bidirectional}
20+
R6Class R base <> sub {bidirectional}
21+
RMarkdown Markdown base <= sub {dedicated}
22+
RSpec Ruby base => sub {shared}
23+
Rake Ruby base <= sub {dedicated}
24+
RelaxNG XML base <> sub {bidirectional}
25+
S4Class R base <> sub {bidirectional}
26+
SVG XML base <> sub {bidirectional}
27+
SystemdUnit Iniconf base <= sub {dedicated}
28+
TclOO Tcl base <> sub {bidirectional}
29+
TeXBeamer Tex base <> sub {bidirectional}
30+
XSLT XML base <> sub {bidirectional}
31+
YumRepo Iniconf base <= sub {dedicated}

‎Units/parser-kerneldoc.r/dots-in-members.d/args.ctags

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
--sort=no
2+
--languages=+KernelDoc
3+
--fields=+Kl
4+
--extras=+g
5+
--kinds-KernelDoc=*
6+
--kinds-C=
7+
--kinds-CPreProcessor=

‎Units/parser-kerneldoc.r/dots-in-members.d/expected.tags

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
dots in members input.c /^ * DOC: dots in members$/;" doc language:KernelDoc
2+
nested_foobar input.c /^ * struct nested_foobar - a struct with nested unions and structs$/;" struct language:KernelDoc doc:dots in members
3+
memb1 input.c /^ * @memb1: first member of anonymous union\/anonymous struct$/;" member language:KernelDoc struct:dots in members""nested_foobar
4+
memb2 input.c /^ * @memb2: second member of anonymous union\/anonymous struct$/;" member language:KernelDoc struct:dots in members""nested_foobar
5+
memb3 input.c /^ * @memb3: third member of anonymous union\/anonymous struct$/;" member language:KernelDoc struct:dots in members""nested_foobar
6+
memb4 input.c /^ * @memb4: fourth member of anonymous union\/anonymous struct$/;" member language:KernelDoc struct:dots in members""nested_foobar
7+
bar input.c /^ * @bar: non-anonymous union$/;" member language:KernelDoc struct:dots in members""nested_foobar
8+
bar.st1 input.c /^ * @bar.st1: struct st1 inside @bar$/;" member language:KernelDoc struct:dots in members""nested_foobar
9+
bar.st2 input.c /^ * @bar.st2: struct st2 inside @bar$/;" member language:KernelDoc struct:dots in members""nested_foobar
10+
bar.st1.memb1 input.c /^ * @bar.st1.memb1: first member of struct st1 on union bar$/;" member language:KernelDoc struct:dots in members""nested_foobar
11+
bar.st1.memb2 input.c /^ * @bar.st1.memb2: second member of struct st1 on union bar$/;" member language:KernelDoc struct:dots in members""nested_foobar
12+
bar.st2.memb1 input.c /^ * @bar.st2.memb1: first member of struct st2 on union bar$/;" member language:KernelDoc struct:dots in members""nested_foobar
13+
bar.st2.memb2 input.c /^ * @bar.st2.memb2: second member of struct st2 on union bar$/;" member language:KernelDoc struct:dots in members""nested_foobar

‎Units/parser-kerneldoc.r/dots-in-members.d/input.c

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
/* Taken from linux/Documentation/doc-guide/kernel-doc.rst */
2+
/**
3+
* DOC: dots in members
4+
*/
5+
6+
/**
7+
* struct nested_foobar - a struct with nested unions and structs
8+
* @memb1: first member of anonymous union/anonymous struct
9+
* @memb2: second member of anonymous union/anonymous struct
10+
* @memb3: third member of anonymous union/anonymous struct
11+
* @memb4: fourth member of anonymous union/anonymous struct
12+
* @bar: non-anonymous union
13+
* @bar.st1: struct st1 inside @bar
14+
* @bar.st2: struct st2 inside @bar
15+
* @bar.st1.memb1: first member of struct st1 on union bar
16+
* @bar.st1.memb2: second member of struct st1 on union bar
17+
* @bar.st2.memb1: first member of struct st2 on union bar
18+
* @bar.st2.memb2: second member of struct st2 on union bar
19+
*/
20+
struct nested_foobar {
21+
/* Anonymous union/struct*/
22+
union {
23+
struct {
24+
int memb1;
25+
int memb2;
26+
};
27+
struct {
28+
void *memb3;
29+
int memb4;
30+
};
31+
};
32+
union {
33+
struct {
34+
int memb1;
35+
int memb2;
36+
} st1;
37+
struct {
38+
void *memb1;
39+
int memb2;
40+
} st2;
41+
} bar;
42+
};

‎Units/parser-kerneldoc.r/inline.d/args.ctags

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
--sort=no
2+
--languages=+KernelDoc
3+
--fields=+Kl
4+
--extras=+g
5+
--kinds-KernelDoc=*
6+
--kinds-C=
7+
--kinds-CPreProcessor=

‎Units/parser-kerneldoc.r/inline.d/expected.tags

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
in-line input.c /^ * DOC: in-line$/;" doc language:KernelDoc
2+
foo input.c /^ * struct foo - Brief description.$/;" struct language:KernelDoc doc:in-line
3+
foo input.c /^ * @foo: The Foo member.$/;" member language:KernelDoc struct:in-line""foo
4+
bar input.c /^ * @bar: The Bar member.$/;" member language:KernelDoc struct:in-line""foo
5+
baz input.c /^ * @baz: The Baz member.$/;" member language:KernelDoc struct:in-line""foo
6+
foobar input.c /^ \/** @foobar: Single line description. *\/$/;" member language:KernelDoc struct:in-line""foo
7+
bar2 input.c /^ \/** @bar2: Description for struct @bar2 inside @foo *\/$/;" member language:KernelDoc struct:in-line""foo
8+
bar2.barbar input.c /^ * @bar2.barbar: Description for @barbar inside @foo.bar2$/;" member language:KernelDoc struct:in-line""foo

‎Units/parser-kerneldoc.r/inline.d/input.c

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
/* Taken from linux/Documentation/doc-guide/kernel-doc.rst */
2+
/**
3+
* DOC: in-line
4+
*/
5+
6+
/**
7+
* struct foo - Brief description.
8+
* @foo: The Foo member.
9+
*/
10+
struct foo {
11+
int foo;
12+
/**
13+
* @bar: The Bar member.
14+
*/
15+
int bar;
16+
/**
17+
* @baz: The Baz member.
18+
*
19+
* Here, the member description may contain several paragraphs.
20+
*/
21+
int baz;
22+
union {
23+
/** @foobar: Single line description. */
24+
int foobar;
25+
};
26+
/** @bar2: Description for struct @bar2 inside @foo */
27+
struct {
28+
/**
29+
* @bar2.barbar: Description for @barbar inside @foo.bar2
30+
*/
31+
int barbar;
32+
} bar2;
33+
};

‎Units/parser-kerneldoc.r/simple.d/args.ctags

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
--sort=no
2+
--languages=+KernelDoc
3+
--fields=+Kl
4+
--extras=+g
5+
--kinds-KernelDoc=*
6+
--kinds-C=
7+
--kinds-CPreProcessor=

‎Units/parser-kerneldoc.r/simple.d/expected.tags

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
simple input.c /^ * DOC: simple$/;" doc language:KernelDoc
2+
cpuhp_invoke_callback input.c /^ * cpuhp_invoke_callback - Invoke the callbacks for a given state$/;" unknown language:KernelDoc doc:simple
3+
cpu input.c /^ * @cpu: The cpu for which the callback should be invoked$/;" parameter language:KernelDoc unknown:simple""cpuhp_invoke_callback
4+
state input.c /^ * @state: The state to do callbacks for$/;" parameter language:KernelDoc unknown:simple""cpuhp_invoke_callback
5+
bringup input.c /^ * @bringup: True if the bringup callback should be invoked$/;" parameter language:KernelDoc unknown:simple""cpuhp_invoke_callback
6+
node input.c /^ * @node: For multi-instance, do a single entry callback for install\/remove$/;" parameter language:KernelDoc unknown:simple""cpuhp_invoke_callback
7+
lastp input.c /^ * @lastp: For multi-instance rollback, remember how far we got$/;" parameter language:KernelDoc unknown:simple""cpuhp_invoke_callback
8+
ACPI_DEVICE_CLASS input.c /^ * ACPI_DEVICE_CLASS - macro used to describe an ACPI device with$/;" unknown language:KernelDoc doc:simple
9+
_cls input.c /^ * @_cls : the class, subclass, prog-if triple for this device$/;" parameter language:KernelDoc unknown:simple""ACPI_DEVICE_CLASS
10+
_msk input.c /^ * @_msk : the class mask for this device$/;" parameter language:KernelDoc unknown:simple""ACPI_DEVICE_CLASS
11+
acpi_dma_spec input.c /^ * struct acpi_dma_spec - slave device DMA resources$/;" struct language:KernelDoc doc:simple
12+
chan_id input.c /^ * @chan_id: channel unique id$/;" member language:KernelDoc struct:simple""acpi_dma_spec
13+
slave_id input.c /^ * @slave_id: request line unique id$/;" member language:KernelDoc struct:simple""acpi_dma_spec
14+
dev input.c /^ * @dev: struct device of the DMA controller to be used in the filter$/;" member language:KernelDoc struct:simple""acpi_dma_spec
15+
dma_cookie_t input.c /^ * typedef dma_cookie_t - an opaque DMA cookie$/;" typedef language:KernelDoc doc:simple
16+
coresight_dev_subtype input.c /^ * union coresight_dev_subtype - further characterisation of a type$/;" union language:KernelDoc doc:simple
17+
sink_subtype input.c /^ * @sink_subtype: type of sink this component is, as defined$/;" member language:KernelDoc union:simple""coresight_dev_subtype
18+
link_subtype input.c /^ * @link_subtype: type of link this component is, as defined$/;" member language:KernelDoc union:simple""coresight_dev_subtype
19+
source_subtype input.c /^ * @source_subtype: type of source this component is, as defined$/;" member language:KernelDoc union:simple""coresight_dev_subtype
20+
helper_subtype input.c /^ * @helper_subtype: type of helper this component is, as defined$/;" member language:KernelDoc union:simple""coresight_dev_subtype
21+
ect_subtype input.c /^ * @ect_subtype: type of cross trigger this component is, as$/;" member language:KernelDoc union:simple""coresight_dev_subtype

‎Units/parser-kerneldoc.r/simple.d/input.c

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
/* Taken from linux/kernel/cpu.c */
2+
/**
3+
* DOC: simple
4+
*/
5+
6+
/**
7+
* cpuhp_invoke_callback - Invoke the callbacks for a given state
8+
* @cpu: The cpu for which the callback should be invoked
9+
* @state: The state to do callbacks for
10+
* @bringup: True if the bringup callback should be invoked
11+
* @node: For multi-instance, do a single entry callback for install/remove
12+
* @lastp: For multi-instance rollback, remember how far we got
13+
*
14+
* Called from cpu hotplug and from the state register machinery.
15+
*
16+
* Return: %0 on success or a negative errno code
17+
*/
18+
static int cpuhp_invoke_callback(unsigned int cpu, enum cpuhp_state state,
19+
bool bringup, struct hlist_node *node,
20+
struct hlist_node **lastp)
21+
{
22+
return 0;
23+
}
24+
25+
/* Taken from linux/include/linux/acpi.h */
26+
/**
27+
* ACPI_DEVICE_CLASS - macro used to describe an ACPI device with
28+
* the PCI-defined class-code information
29+
*
30+
* @_cls : the class, subclass, prog-if triple for this device
31+
* @_msk : the class mask for this device
32+
*
33+
* This macro is used to create a struct acpi_device_id that matches a
34+
* specific PCI class. The .id and .driver_data fields will be left
35+
* initialized with the default value.
36+
*/
37+
#define ACPI_DEVICE_CLASS(_cls, _msk) .cls = (_cls), .cls_msk = (_msk),
38+
39+
/* Taken from linux/include/linux/acpi_dma.h */
40+
/**
41+
* struct acpi_dma_spec - slave device DMA resources
42+
* @chan_id: channel unique id
43+
* @slave_id: request line unique id
44+
* @dev: struct device of the DMA controller to be used in the filter
45+
* function
46+
*/
47+
struct acpi_dma_spec {
48+
int chan_id;
49+
int slave_id;
50+
struct device *dev;
51+
};
52+
53+
/* Taken from linux/include/linux/dmaengine.h */
54+
/**
55+
* typedef dma_cookie_t - an opaque DMA cookie
56+
*
57+
* if dma_cookie_t is >0 it's a DMA request cookie, <0 it's an error code
58+
*/
59+
typedef s32 dma_cookie_t;
60+
61+
/* Taken from linux/include/linux/coresight.h */
62+
/**
63+
* union coresight_dev_subtype - further characterisation of a type
64+
* @sink_subtype: type of sink this component is, as defined
65+
* by @coresight_dev_subtype_sink.
66+
* @link_subtype: type of link this component is, as defined
67+
* by @coresight_dev_subtype_link.
68+
* @source_subtype: type of source this component is, as defined
69+
* by @coresight_dev_subtype_source.
70+
* @helper_subtype: type of helper this component is, as defined
71+
* by @coresight_dev_subtype_helper.
72+
* @ect_subtype: type of cross trigger this component is, as
73+
* defined by @coresight_dev_subtype_ect
74+
*/
75+
union coresight_dev_subtype {
76+
/* We have some devices which acts as LINK and SINK */
77+
struct {
78+
enum coresight_dev_subtype_sink sink_subtype;
79+
enum coresight_dev_subtype_link link_subtype;
80+
};
81+
enum coresight_dev_subtype_source source_subtype;
82+
enum coresight_dev_subtype_helper helper_subtype;
83+
enum coresight_dev_subtype_ect ect_subtype;
84+
};

‎Units/parser-kerneldoc.r/typedef-with-prototype.d/args.ctags

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
--sort=no
2+
--languages=+KernelDoc
3+
--fields=+Kl
4+
--extras=+g
5+
--kinds-KernelDoc=*
6+
--kinds-C=
7+
--kinds-CPreProcessor=

‎Units/parser-kerneldoc.r/typedef-with-prototype.d/expected.tags

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Typedefs with function prototypes input.c /^ * DOC: Typedefs with function prototypes$/;" doc language:KernelDoc
2+
type_name input.c /^ * typedef type_name - Brief description.$/;" typedef language:KernelDoc doc:Typedefs with function prototypes
3+
arg1 input.c /^ * @arg1: description of arg1$/;" parameter language:KernelDoc typedef:Typedefs with function prototypes""type_name
4+
arg2 input.c /^ * @arg2: description of arg2$/;" parameter language:KernelDoc typedef:Typedefs with function prototypes""type_name

‎Units/parser-kerneldoc.r/typedef-with-prototype.d/input.c

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
/* Taken from linux/Documentation/doc-guide/kernel-doc.rst */
2+
/**
3+
* DOC: Typedefs with function prototypes
4+
*/
5+
6+
/**
7+
* typedef type_name - Brief description.
8+
* @arg1: description of arg1
9+
* @arg2: description of arg2
10+
*
11+
* Description of the type.
12+
*
13+
* Context: Locking context.
14+
* Return: Meaning of the return value.
15+
*/
16+
typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);

‎docs/news.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -429,6 +429,7 @@ The following parsers have been added:
429429
* JSON
430430
* Julia
431431
* Kconfig *optlib*
432+
* KernelDoc *CPreProcessor based subparser"
432433
* Kotlin *peg/packcc*
433434
* GNU linker script(LdScript)
434435
* LEX *optlib*

‎main/parsers_p.h

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,7 @@
115115
JsonParser, \
116116
JuliaParser, \
117117
KconfigParser, \
118+
KernelDocParser, \
118119
LdScriptParser, \
119120
LEXParser, \
120121
LispParser, \

0 commit comments

Comments
 (0)