Skip to content

Commit dfdadb1

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 3156388 commit dfdadb1

File tree

17 files changed

+539
-30
lines changed

17 files changed

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

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

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

‎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: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
foo input.c /^ * struct foo - Brief description.$/;" struct language:KernelDoc
2+
foo input.c /^ * @foo: The Foo member.$/;" member language:KernelDoc struct:foo
3+
@bar input.c /^ * @bar: The Bar member.$/;" unknown language:GtkDoc
4+
@baz input.c /^ * @baz: The Baz member.$/;" unknown language:GtkDoc
5+
@foobar input.c /^ \/** @foobar: Single line description. *\/$/;" unknown language:GtkDoc
6+
@bar2 input.c /^ \/** @bar2: Description for struct @bar2 inside @foo *\/$/;" unknown language:GtkDoc
7+
@bar2.barbar input.c /^ * @bar2.barbar: Description for @barbar inside @foo.bar2$/;" unknown language:GtkDoc

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

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

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

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

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

‎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: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
type_name input.c /^ * typedef type_name - Brief description.$/;" typedef language:KernelDoc
2+
arg1 input.c /^ * @arg1: description of arg1$/;" parameter language:KernelDoc typedef:type_name
3+
arg2 input.c /^ * @arg2: description of arg2$/;" parameter language:KernelDoc typedef:type_name

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

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
/* Taken from linux/Documentation/doc-guide/kernel-doc.rst */
2+
/**
3+
* typedef type_name - Brief description.
4+
* @arg1: description of arg1
5+
* @arg2: description of arg2
6+
*
7+
* Description of the type.
8+
*
9+
* Context: Locking context.
10+
* Return: Meaning of the return value.
11+
*/
12+
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)