KernelDoc: new parser

This one is disabled by default.
Give --languages=+KernelDoc for enabling.

Signed-off-by: Masatake YAMATO <yamato@redhat.com>

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

@@ -1,31 +1,32 @@
-#NAME                BASEPARSER DIRECTIONS
-AnsiblePlaybook      Yaml       base <> sub {bidirectional}
-Ant                  XML        base <> sub {bidirectional}
-Autoconf             M4         base <> sub {bidirectional}
-Automake             Make       base <= sub {dedicated}
-Bats                 Sh         base <= sub {dedicated}
-DBusIntrospect       XML        base <> sub {bidirectional}
-FunctionParameters   Perl       base <> sub {bidirectional}
-GemSpec              Ruby       base <= sub {dedicated}
-Glade                XML        base <> sub {bidirectional}
-IPythonCell          Python     base => sub {shared}
-ITcl                 Tcl        base <> sub {bidirectional}
-Maven2               XML        base <> sub {bidirectional}
-Moose                Perl       base <> sub {bidirectional}
-OpenAPI              Yaml       base <> sub {bidirectional}
-PlistXML             XML        base <> sub {bidirectional}
-PythonLoggingConfig  Iniconf    base <> sub {bidirectional}
-QtMoc                C++        base <> sub {bidirectional}
-Quarto               Markdown   base <= sub {dedicated}
-R6Class              R          base <> sub {bidirectional}
-RMarkdown            Markdown   base <= sub {dedicated}
-RSpec                Ruby       base => sub {shared}
-Rake                 Ruby       base <= sub {dedicated}
-RelaxNG              XML        base <> sub {bidirectional}
-S4Class              R          base <> sub {bidirectional}
-SVG                  XML        base <> sub {bidirectional}
-SystemdUnit          Iniconf    base <= sub {dedicated}
-TclOO                Tcl        base <> sub {bidirectional}
-TeXBeamer            Tex        base <> sub {bidirectional}
-XSLT                 XML        base <> sub {bidirectional}
-YumRepo              Iniconf    base <= sub {dedicated}
+#NAME                BASEPARSER    DIRECTIONS
+AnsiblePlaybook      Yaml          base <> sub {bidirectional}
+Ant                  XML           base <> sub {bidirectional}
+Autoconf             M4            base <> sub {bidirectional}
+Automake             Make          base <= sub {dedicated}
+Bats                 Sh            base <= sub {dedicated}
+DBusIntrospect       XML           base <> sub {bidirectional}
+FunctionParameters   Perl          base <> sub {bidirectional}
+GemSpec              Ruby          base <= sub {dedicated}
+Glade                XML           base <> sub {bidirectional}
+IPythonCell          Python        base => sub {shared}
+ITcl                 Tcl           base <> sub {bidirectional}
+KernelDoc            CPreProcessor base => sub {shared}
+Maven2               XML           base <> sub {bidirectional}
+Moose                Perl          base <> sub {bidirectional}
+OpenAPI              Yaml          base <> sub {bidirectional}
+PlistXML             XML           base <> sub {bidirectional}
+PythonLoggingConfig  Iniconf       base <> sub {bidirectional}
+QtMoc                C++           base <> sub {bidirectional}
+Quarto               Markdown      base <= sub {dedicated}
+R6Class              R             base <> sub {bidirectional}
+RMarkdown            Markdown      base <= sub {dedicated}
+RSpec                Ruby          base => sub {shared}
+Rake                 Ruby          base <= sub {dedicated}
+RelaxNG              XML           base <> sub {bidirectional}
+S4Class              R             base <> sub {bidirectional}
+SVG                  XML           base <> sub {bidirectional}
+SystemdUnit          Iniconf       base <= sub {dedicated}
+TclOO                Tcl           base <> sub {bidirectional}
+TeXBeamer            Tex           base <> sub {bidirectional}
+XSLT                 XML           base <> sub {bidirectional}
+YumRepo              Iniconf       base <= sub {dedicated}

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

@@ -0,0 +1,7 @@
+--sort=no
+--languages=+KernelDoc
+--fields=+Kl
+--extras=+g
+--kinds-KernelDoc=*
+--kinds-C=
+--kinds-CPreProcessor=

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

@@ -0,0 +1,13 @@
+dots in members	input.c	/^ * DOC: dots in members$/;"	doc	language:KernelDoc
+nested_foobar	input.c	/^ * struct nested_foobar - a struct with nested unions and structs$/;"	struct	language:KernelDoc	doc:dots in members
+memb1	input.c	/^ * @memb1: first member of anonymous union\/anonymous struct$/;"	member	language:KernelDoc	struct:dots in members""nested_foobar
+memb2	input.c	/^ * @memb2: second member of anonymous union\/anonymous struct$/;"	member	language:KernelDoc	struct:dots in members""nested_foobar
+memb3	input.c	/^ * @memb3: third member of anonymous union\/anonymous struct$/;"	member	language:KernelDoc	struct:dots in members""nested_foobar
+memb4	input.c	/^ * @memb4: fourth member of anonymous union\/anonymous struct$/;"	member	language:KernelDoc	struct:dots in members""nested_foobar
+bar	input.c	/^ * @bar: non-anonymous union$/;"	member	language:KernelDoc	struct:dots in members""nested_foobar
+bar.st1	input.c	/^ * @bar.st1: struct st1 inside @bar$/;"	member	language:KernelDoc	struct:dots in members""nested_foobar
+bar.st2	input.c	/^ * @bar.st2: struct st2 inside @bar$/;"	member	language:KernelDoc	struct:dots in members""nested_foobar
+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
+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
+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
+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

@@ -0,0 +1,42 @@
+/* Taken from linux/Documentation/doc-guide/kernel-doc.rst */
+/**
+ * DOC: dots in members
+ */
+
+/**
+ * struct nested_foobar - a struct with nested unions and structs
+ * @memb1: first member of anonymous union/anonymous struct
+ * @memb2: second member of anonymous union/anonymous struct
+ * @memb3: third member of anonymous union/anonymous struct
+ * @memb4: fourth member of anonymous union/anonymous struct
+ * @bar: non-anonymous union
+ * @bar.st1: struct st1 inside @bar
+ * @bar.st2: struct st2 inside @bar
+ * @bar.st1.memb1: first member of struct st1 on union bar
+ * @bar.st1.memb2: second member of struct st1 on union bar
+ * @bar.st2.memb1: first member of struct st2 on union bar
+ * @bar.st2.memb2: second member of struct st2 on union bar
+ */
+struct nested_foobar {
+  /* Anonymous union/struct*/
+  union {
+    struct {
+      int memb1;
+      int memb2;
+    };
+    struct {
+      void *memb3;
+      int memb4;
+    };
+  };
+  union {
+    struct {
+      int memb1;
+      int memb2;
+    } st1;
+    struct {
+      void *memb1;
+      int memb2;
+    } st2;
+  } bar;
+};

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

@@ -0,0 +1,7 @@
+--sort=no
+--languages=+KernelDoc
+--fields=+Kl
+--extras=+g
+--kinds-KernelDoc=*
+--kinds-C=
+--kinds-CPreProcessor=

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

@@ -0,0 +1,8 @@
+in-line	input.c	/^ * DOC: in-line$/;"	doc	language:KernelDoc
+foo	input.c	/^ * struct foo - Brief description.$/;"	struct	language:KernelDoc	doc:in-line
+foo	input.c	/^ * @foo: The Foo member.$/;"	member	language:KernelDoc	struct:in-line""foo
+bar	input.c	/^       * @bar: The Bar member.$/;"	member	language:KernelDoc	struct:in-line""foo
+baz	input.c	/^       * @baz: The Baz member.$/;"	member	language:KernelDoc	struct:in-line""foo
+foobar	input.c	/^              \/** @foobar: Single line description. *\/$/;"	member	language:KernelDoc	struct:in-line""foo
+bar2	input.c	/^      \/** @bar2: Description for struct @bar2 inside @foo *\/$/;"	member	language:KernelDoc	struct:in-line""foo
+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

@@ -0,0 +1,33 @@
+/* Taken from linux/Documentation/doc-guide/kernel-doc.rst */
+/**
+ * DOC: in-line
+ */
+
+/**
+ * struct foo - Brief description.
+ * @foo: The Foo member.
+ */
+struct foo {
+      int foo;
+      /**
+       * @bar: The Bar member.
+       */
+      int bar;
+      /**
+       * @baz: The Baz member.
+       *
+       * Here, the member description may contain several paragraphs.
+       */
+      int baz;
+      union {
+              /** @foobar: Single line description. */
+              int foobar;
+      };
+      /** @bar2: Description for struct @bar2 inside @foo */
+      struct {
+              /**
+               * @bar2.barbar: Description for @barbar inside @foo.bar2
+               */
+              int barbar;
+      } bar2;
+};

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

@@ -0,0 +1,7 @@
+--sort=no
+--languages=+KernelDoc
+--fields=+Kl
+--extras=+g
+--kinds-KernelDoc=*
+--kinds-C=
+--kinds-CPreProcessor=

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

@@ -0,0 +1,29 @@
+simple	input.c	/^ * DOC: simple$/;"	doc	language:KernelDoc
+cpuhp_invoke_callback	input.c	/^ * cpuhp_invoke_callback - Invoke the callbacks for a given state$/;"	unknown	language:KernelDoc	doc:simple
+cpu	input.c	/^ * @cpu:	The cpu for which the callback should be invoked$/;"	parameter	language:KernelDoc	unknown:simple""cpuhp_invoke_callback
+state	input.c	/^ * @state:	The state to do callbacks for$/;"	parameter	language:KernelDoc	unknown:simple""cpuhp_invoke_callback
+bringup	input.c	/^ * @bringup:	True if the bringup callback should be invoked$/;"	parameter	language:KernelDoc	unknown:simple""cpuhp_invoke_callback
+node	input.c	/^ * @node:	For multi-instance, do a single entry callback for install\/remove$/;"	parameter	language:KernelDoc	unknown:simple""cpuhp_invoke_callback
+lastp	input.c	/^ * @lastp:	For multi-instance rollback, remember how far we got$/;"	parameter	language:KernelDoc	unknown:simple""cpuhp_invoke_callback
+ACPI_DEVICE_CLASS	input.c	/^ * ACPI_DEVICE_CLASS - macro used to describe an ACPI device with$/;"	unknown	language:KernelDoc	doc:simple
+_cls 	input.c	/^ * @_cls : the class, subclass, prog-if triple for this device$/;"	parameter	language:KernelDoc	unknown:simple""ACPI_DEVICE_CLASS
+_msk 	input.c	/^ * @_msk : the class mask for this device$/;"	parameter	language:KernelDoc	unknown:simple""ACPI_DEVICE_CLASS
+acpi_dma_spec	input.c	/^ * struct acpi_dma_spec - slave device DMA resources$/;"	struct	language:KernelDoc	doc:simple
+chan_id	input.c	/^ * @chan_id:	channel unique id$/;"	member	language:KernelDoc	struct:simple""acpi_dma_spec
+slave_id	input.c	/^ * @slave_id:	request line unique id$/;"	member	language:KernelDoc	struct:simple""acpi_dma_spec
+dev	input.c	/^ * @dev:	struct device of the DMA controller to be used in the filter$/;"	member	language:KernelDoc	struct:simple""acpi_dma_spec
+dma_cookie_t	input.c	/^ * typedef dma_cookie_t - an opaque DMA cookie$/;"	typedef	language:KernelDoc	doc:simple
+coresight_dev_subtype	input.c	/^ * union coresight_dev_subtype - further characterisation of a type$/;"	union	language:KernelDoc	doc:simple
+sink_subtype	input.c	/^ * @sink_subtype:	type of sink this component is, as defined$/;"	member	language:KernelDoc	union:simple""coresight_dev_subtype
+link_subtype	input.c	/^ * @link_subtype:	type of link this component is, as defined$/;"	member	language:KernelDoc	union:simple""coresight_dev_subtype
+source_subtype	input.c	/^ * @source_subtype:	type of source this component is, as defined$/;"	member	language:KernelDoc	union:simple""coresight_dev_subtype
+helper_subtype	input.c	/^ * @helper_subtype:	type of helper this component is, as defined$/;"	member	language:KernelDoc	union:simple""coresight_dev_subtype
+ect_subtype	input.c	/^ * @ect_subtype:        type of cross trigger this component is, as$/;"	member	language:KernelDoc	union:simple""coresight_dev_subtype
+smp_cond_load_relaxed	input-0.c	/^ * smp_cond_load_relaxed() - (Spin) wait for cond with no ordering guarantees$/;"	function	language:KernelDoc
+ptr	input-0.c	/^ * @ptr: pointer to the variable to wait on$/;"	parameter	language:KernelDoc	function:smp_cond_load_relaxed
+cond	input-0.c	/^ * @cond: boolean expression to wait for$/;"	parameter	language:KernelDoc	function:smp_cond_load_relaxed
+extra test input	input-0.c	/^ * DOC: extra test input$/;"	doc	language:KernelDoc
+kunit_status	input-0.c	/^ * enum kunit_status - Type of result for a test or test suite$/;"	enum	language:KernelDoc	doc:extra test input
+KUNIT_SUCCESS	input-0.c	/^ * @KUNIT_SUCCESS: Denotes the test suite has not failed nor been skipped$/;"	enumerator	language:KernelDoc	enum:extra test input""kunit_status
+KUNIT_FAILURE	input-0.c	/^ * @KUNIT_FAILURE: Denotes the test has failed.$/;"	enumerator	language:KernelDoc	enum:extra test input""kunit_status
+KUNIT_SKIPPED	input-0.c	/^ * @KUNIT_SKIPPED: Denotes the test has been skipped.$/;"	enumerator	language:KernelDoc	enum:extra test input""kunit_status

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

@@ -0,0 +1,41 @@
+/* Taken from linux/include/asm-generic/barrier.h */
+/**
+ * smp_cond_load_relaxed() - (Spin) wait for cond with no ordering guarantees
+ * @ptr: pointer to the variable to wait on
+ * @cond: boolean expression to wait for
+ *
+ * Equivalent to using READ_ONCE() on the condition variable.
+ *
+ * Due to C lacking lambda expressions we load the value of *ptr into a
+ * pre-named variable @VAL to be used in @cond.
+ */
+#ifndef smp_cond_load_relaxed
+#define smp_cond_load_relaxed(ptr, cond_expr) ({		\
+	typeof(ptr) __PTR = (ptr);				\
+	__unqual_scalar_typeof(*ptr) VAL;			\
+	for (;;) {						\
+		VAL = READ_ONCE(*__PTR);			\
+		if (cond_expr)					\
+			break;					\
+		cpu_relax();					\
+	}							\
+	(typeof(*ptr))VAL;					\
+})
+#endif
+
+/**
+ * DOC: extra test input
+ */
+
+/* Taken from linux/include/kunit/test.h */
+/**
+ * enum kunit_status - Type of result for a test or test suite
+ * @KUNIT_SUCCESS: Denotes the test suite has not failed nor been skipped
+ * @KUNIT_FAILURE: Denotes the test has failed.
+ * @KUNIT_SKIPPED: Denotes the test has been skipped.
+ */
+enum kunit_status {
+	KUNIT_SUCCESS,
+	KUNIT_FAILURE,
+	KUNIT_SKIPPED,
+};

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

@@ -0,0 +1,84 @@
+/* Taken from linux/kernel/cpu.c */
+/**
+ * DOC: simple
+ */
+
+/**
+ * cpuhp_invoke_callback - Invoke the callbacks for a given state
+ * @cpu:	The cpu for which the callback should be invoked
+ * @state:	The state to do callbacks for
+ * @bringup:	True if the bringup callback should be invoked
+ * @node:	For multi-instance, do a single entry callback for install/remove
+ * @lastp:	For multi-instance rollback, remember how far we got
+ *
+ * Called from cpu hotplug and from the state register machinery.
+ *
+ * Return: %0 on success or a negative errno code
+ */
+static int cpuhp_invoke_callback(unsigned int cpu, enum cpuhp_state state,
+				 bool bringup, struct hlist_node *node,
+				 struct hlist_node **lastp)
+{
+	return 0;
+}
+
+/* Taken from linux/include/linux/acpi.h */
+/**
+ * ACPI_DEVICE_CLASS - macro used to describe an ACPI device with
+ * the PCI-defined class-code information
+ *
+ * @_cls : the class, subclass, prog-if triple for this device
+ * @_msk : the class mask for this device
+ *
+ * This macro is used to create a struct acpi_device_id that matches a
+ * specific PCI class. The .id and .driver_data fields will be left
+ * initialized with the default value.
+ */
+#define ACPI_DEVICE_CLASS(_cls, _msk)	.cls = (_cls), .cls_msk = (_msk),
+
+/* Taken from linux/include/linux/acpi_dma.h */
+/**
+ * struct acpi_dma_spec - slave device DMA resources
+ * @chan_id:	channel unique id
+ * @slave_id:	request line unique id
+ * @dev:	struct device of the DMA controller to be used in the filter
+ *		function
+ */
+struct acpi_dma_spec {
+	int		chan_id;
+	int		slave_id;
+	struct device	*dev;
+};
+
+/* Taken from linux/include/linux/dmaengine.h */
+/**
+ * typedef dma_cookie_t - an opaque DMA cookie
+ *
+ * if dma_cookie_t is >0 it's a DMA request cookie, <0 it's an error code
+ */
+typedef s32 dma_cookie_t;
+
+/* Taken from linux/include/linux/coresight.h */
+/**
+ * union coresight_dev_subtype - further characterisation of a type
+ * @sink_subtype:	type of sink this component is, as defined
+ *			by @coresight_dev_subtype_sink.
+ * @link_subtype:	type of link this component is, as defined
+ *			by @coresight_dev_subtype_link.
+ * @source_subtype:	type of source this component is, as defined
+ *			by @coresight_dev_subtype_source.
+ * @helper_subtype:	type of helper this component is, as defined
+ *			by @coresight_dev_subtype_helper.
+ * @ect_subtype:        type of cross trigger this component is, as
+ *			defined by @coresight_dev_subtype_ect
+ */
+union coresight_dev_subtype {
+	/* We have some devices which acts as LINK and SINK */
+	struct {
+		enum coresight_dev_subtype_sink sink_subtype;
+		enum coresight_dev_subtype_link link_subtype;
+	};
+	enum coresight_dev_subtype_source source_subtype;
+	enum coresight_dev_subtype_helper helper_subtype;
+	enum coresight_dev_subtype_ect ect_subtype;
+};

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

@@ -0,0 +1,7 @@
+--sort=no
+--languages=+KernelDoc
+--fields=+Kl
+--extras=+g
+--kinds-KernelDoc=*
+--kinds-C=
+--kinds-CPreProcessor=

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

@@ -0,0 +1,4 @@
+Typedefs with function prototypes	input.c	/^ * DOC: Typedefs with function prototypes$/;"	doc	language:KernelDoc
+type_name	input.c	/^ * typedef type_name - Brief description.$/;"	typedef	language:KernelDoc	doc:Typedefs with function prototypes
+arg1	input.c	/^ * @arg1: description of arg1$/;"	parameter	language:KernelDoc	typedef:Typedefs with function prototypes""type_name
+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

@@ -0,0 +1,16 @@
+/* Taken from linux/Documentation/doc-guide/kernel-doc.rst */
+/**
+ * DOC: Typedefs with function prototypes
+ */
+
+/**
+ * typedef type_name - Brief description.
+ * @arg1: description of arg1
+ * @arg2: description of arg2
+ *
+ * Description of the type.
+ *
+ * Context: Locking context.
+ * Return: Meaning of the return value.
+ */
+ typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);

docs/news.rst

@@ -429,6 +429,7 @@ The following parsers have been added:
 * JSON
 * Julia
 * Kconfig *optlib*
+* KernelDoc *CPreProcessor based subparser"
 * Kotlin *peg/packcc*
 * GNU linker script(LdScript)
 * LEX *optlib*

main/parsers_p.h

@@ -115,6 +115,7 @@
 	JsonParser, \
 	JuliaParser, \
 	KconfigParser, \
+	KernelDocParser, \
 	LdScriptParser, \
 	LEXParser, \
 	LispParser, \