* [PATCH v4 01/18] docs: kernel-doc.rst: better describe kernel-doc arguments
2017-12-18 12:30 [PATCH v4 00/18] kernel-doc: add supported to document nested structs Mauro Carvalho Chehab
@ 2017-12-18 12:30 ` Mauro Carvalho Chehab
2017-12-18 12:30 ` [PATCH v4 02/18] docs: kernel-doc.rst: improve private members description Mauro Carvalho Chehab
` (17 subsequent siblings)
18 siblings, 0 replies; 28+ messages in thread
From: Mauro Carvalho Chehab @ 2017-12-18 12:30 UTC (permalink / raw)
To: Linux Media Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab,
Linux Doc Mailing List, Tom Saeger
Add a new section to describe kernel-doc arguments,
adding examples about how identation should happen, as failing
to do that causes Sphinx to do the wrong thing.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/doc-guide/kernel-doc.rst | 44 +++++++++++++++++++++++++++++++---
1 file changed, 41 insertions(+), 3 deletions(-)
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index 0268335414ce..f1c03c16f03b 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -112,16 +112,17 @@ Example kernel-doc function comment::
/**
* foobar() - Brief description of foobar.
- * @arg: Description of argument of foobar.
+ * @argument1: Description of parameter argument1 of foobar.
+ * @argument2: Description of parameter argument2 of foobar.
*
* Longer description of foobar.
*
* Return: Description of return value of foobar.
*/
- int foobar(int arg)
+ int foobar(int argument1, char *argument2)
The format is similar for documentation for structures, enums, paragraphs,
-etc. See the sections below for details.
+etc. See the sections below for specific details of each type.
The kernel-doc structure is extracted from the comments, and proper `Sphinx C
Domain`_ function and type descriptions with anchors are generated for them. The
@@ -130,6 +131,43 @@ cross-references. See below for details.
.. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html
+
+Parameters and member arguments
+-------------------------------
+
+The kernel-doc function comments describe each parameter to the function and
+function typedefs or each member of struct/union, in order, with the
+``@argument:`` descriptions. For each non-private member argument, one
+``@argument`` definition is needed.
+
+The ``@argument:`` descriptions begin on the very next line following
+the opening brief function description line, with no intervening blank
+comment lines.
+
+The ``@argument:`` descriptions may span multiple lines.
+
+.. note::
+
+ If the ``@argument`` description has multiple lines, the continuation
+ of the description should be starting exactly at the same column as
+ the previous line, e. g.::
+
+ * @argument: some long description
+ * that continues on next lines
+
+ or::
+
+ * @argument:
+ * some long description
+ * that continues on next lines
+
+If a function or typedef parameter argument is ``...`` (e. g. a variable
+number of arguments), its description should be listed in kernel-doc
+notation as::
+
+ * @...: description
+
+
Highlights and cross-references
-------------------------------
--
2.14.3
^ permalink raw reply related [flat|nested] 28+ messages in thread* [PATCH v4 02/18] docs: kernel-doc.rst: improve private members description
2017-12-18 12:30 [PATCH v4 00/18] kernel-doc: add supported to document nested structs Mauro Carvalho Chehab
2017-12-18 12:30 ` [PATCH v4 01/18] docs: kernel-doc.rst: better describe kernel-doc arguments Mauro Carvalho Chehab
@ 2017-12-18 12:30 ` Mauro Carvalho Chehab
2017-12-18 12:30 ` [PATCH v4 03/18] docs: kernel-doc.rst: improve function documentation section Mauro Carvalho Chehab
` (16 subsequent siblings)
18 siblings, 0 replies; 28+ messages in thread
From: Mauro Carvalho Chehab @ 2017-12-18 12:30 UTC (permalink / raw)
To: Linux Media Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab,
Linux Doc Mailing List, Tom Saeger
The private members section can now be moved to be together
with the arguments section. Move it there and add an example
about the usage of public:
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/doc-guide/kernel-doc.rst | 56 ++++++++++++++++++----------------
1 file changed, 30 insertions(+), 26 deletions(-)
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index f1c03c16f03b..7cf58c3489de 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -167,6 +167,36 @@ notation as::
* @...: description
+Private members
+~~~~~~~~~~~~~~~
+
+Inside a struct or union description, you can use the ``private:`` and
+``public:`` comment tags. Structure fields that are inside a ``private:``
+area are not listed in the generated output documentation.
+
+The ``private:`` and ``public:`` tags must begin immediately following a
+``/*`` comment marker. They may optionally include comments between the
+``:`` and the ending ``*/`` marker.
+
+Example::
+
+ /**
+ * struct my_struct - short description
+ * @a: first member
+ * @b: second member
+ * @d: fourth member
+ *
+ * Longer description
+ */
+ struct my_struct {
+ int a;
+ int b;
+ /* private: internal use only */
+ int c;
+ /* public: the next one is public */
+ int d;
+ };
+
Highlights and cross-references
-------------------------------
@@ -332,32 +362,6 @@ on a line of their own, like all other kernel-doc comments::
int foobar;
}
-Private members
-~~~~~~~~~~~~~~~
-
-Inside a struct description, you can use the "private:" and "public:" comment
-tags. Structure fields that are inside a "private:" area are not listed in the
-generated output documentation. The "private:" and "public:" tags must begin
-immediately following a ``/*`` comment marker. They may optionally include
-comments between the ``:`` and the ending ``*/`` marker.
-
-Example::
-
- /**
- * struct my_struct - short description
- * @a: first member
- * @b: second member
- *
- * Longer description
- */
- struct my_struct {
- int a;
- int b;
- /* private: internal use only */
- int c;
- };
-
-
Typedef documentation
---------------------
--
2.14.3
^ permalink raw reply related [flat|nested] 28+ messages in thread* [PATCH v4 03/18] docs: kernel-doc.rst: improve function documentation section
2017-12-18 12:30 [PATCH v4 00/18] kernel-doc: add supported to document nested structs Mauro Carvalho Chehab
2017-12-18 12:30 ` [PATCH v4 01/18] docs: kernel-doc.rst: better describe kernel-doc arguments Mauro Carvalho Chehab
2017-12-18 12:30 ` [PATCH v4 02/18] docs: kernel-doc.rst: improve private members description Mauro Carvalho Chehab
@ 2017-12-18 12:30 ` Mauro Carvalho Chehab
2017-12-18 12:30 ` [PATCH v4 04/18] docs: kernel-doc.rst: improve structs chapter Mauro Carvalho Chehab
` (15 subsequent siblings)
18 siblings, 0 replies; 28+ messages in thread
From: Mauro Carvalho Chehab @ 2017-12-18 12:30 UTC (permalink / raw)
To: Linux Media Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab,
Linux Doc Mailing List, Tom Saeger
Move its contents to happen earlier and improve the description
of return values, adding a subsection to it. Most of the contents
there came from kernel-doc-nano-HOWTO.txt.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/doc-guide/kernel-doc.rst | 100 ++++++++++++++++++++-------------
1 file changed, 61 insertions(+), 39 deletions(-)
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index 7cf58c3489de..3aac228fc346 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -197,6 +197,67 @@ Example::
int d;
};
+Function documentation
+----------------------
+
+The general format of a function and function-like macro kernel-doc comment is::
+
+ /**
+ * function_name() - Brief description of function.
+ * @arg1: Describe the first argument.
+ * @arg2: Describe the second argument.
+ * One can provide multiple line descriptions
+ * for arguments.
+ *
+ * A longer description, with more discussion of the function function_name()
+ * that might be useful to those using or modifying it. Begins with an
+ * empty comment line, and may include additional embedded empty
+ * comment lines.
+ *
+ * The longer description may have multiple paragraphs.
+ *
+ * Return: Describe the return value of foobar.
+ *
+ * The return value description can also have multiple paragraphs, and should
+ * be placed at the end of the comment block.
+ */
+
+The brief description following the function name may span multiple lines, and
+ends with an argument description, a blank comment line, or the end of the
+comment block.
+
+Return values
+~~~~~~~~~~~~~
+
+The return value, if any, should be described in a dedicated section
+named ``Return``.
+
+.. note::
+
+ #) The multi-line descriptive text you provide does *not* recognize
+ line breaks, so if you try to format some text nicely, as in::
+
+ * Return:
+ * 0 - OK
+ * -EINVAL - invalid argument
+ * -ENOMEM - out of memory
+
+ this will all run together and produce::
+
+ Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory
+
+ So, in order to produce the desired line breaks, you need to use a
+ ReST list, e. g.::
+
+ * Return:
+ * * 0 - OK to runtime suspend the device
+ * * -EBUSY - Device should not be runtime suspended
+
+ #) If the descriptive text you provide has lines that begin with
+ some phrase followed by a colon, each of those phrases will be taken
+ as a new section heading, with probably won't produce the desired
+ effect.
+
Highlights and cross-references
-------------------------------
@@ -269,45 +330,6 @@ cross-references.
For further details, please refer to the `Sphinx C Domain`_ documentation.
-Function documentation
-----------------------
-
-The general format of a function and function-like macro kernel-doc comment is::
-
- /**
- * function_name() - Brief description of function.
- * @arg1: Describe the first argument.
- * @arg2: Describe the second argument.
- * One can provide multiple line descriptions
- * for arguments.
- *
- * A longer description, with more discussion of the function function_name()
- * that might be useful to those using or modifying it. Begins with an
- * empty comment line, and may include additional embedded empty
- * comment lines.
- *
- * The longer description may have multiple paragraphs.
- *
- * Return: Describe the return value of foobar.
- *
- * The return value description can also have multiple paragraphs, and should
- * be placed at the end of the comment block.
- */
-
-The brief description following the function name may span multiple lines, and
-ends with an ``@argument:`` description, a blank comment line, or the end of the
-comment block.
-
-The kernel-doc function comments describe each parameter to the function, in
-order, with the ``@argument:`` descriptions. The ``@argument:`` descriptions
-must begin on the very next line following the opening brief function
-description line, with no intervening blank comment lines. The ``@argument:``
-descriptions may span multiple lines. The continuation lines may contain
-indentation. If a function parameter is ``...`` (varargs), it should be listed
-in kernel-doc notation as: ``@...:``.
-
-The return value, if any, should be described in a dedicated section at the end
-of the comment starting with "Return:".
Structure, union, and enumeration documentation
-----------------------------------------------
--
2.14.3
^ permalink raw reply related [flat|nested] 28+ messages in thread* [PATCH v4 04/18] docs: kernel-doc.rst: improve structs chapter
2017-12-18 12:30 [PATCH v4 00/18] kernel-doc: add supported to document nested structs Mauro Carvalho Chehab
` (2 preceding siblings ...)
2017-12-18 12:30 ` [PATCH v4 03/18] docs: kernel-doc.rst: improve function documentation section Mauro Carvalho Chehab
@ 2017-12-18 12:30 ` Mauro Carvalho Chehab
2017-12-18 12:30 ` [PATCH v4 05/18] docs: kernel-doc.rst: improve typedef documentation Mauro Carvalho Chehab
` (14 subsequent siblings)
18 siblings, 0 replies; 28+ messages in thread
From: Mauro Carvalho Chehab @ 2017-12-18 12:30 UTC (permalink / raw)
To: Linux Media Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab,
Linux Doc Mailing List, Tom Saeger
There is a mess on this chapter: it suggests that even
enums and unions should be documented with "struct". That's
not the way it should be ;-)
Fix it and move it to happen earlier.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/doc-guide/kernel-doc.rst | 48 +++++++++++++++++-----------------
1 file changed, 24 insertions(+), 24 deletions(-)
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index 3aac228fc346..e3e82f8f4de5 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -258,6 +258,30 @@ named ``Return``.
as a new section heading, with probably won't produce the desired
effect.
+Structure, union, and enumeration documentation
+-----------------------------------------------
+
+The general format of a struct, union, and enum kernel-doc comment is::
+
+ /**
+ * struct struct_name - Brief description.
+ * @argument: Description of member member_name.
+ *
+ * Description of the structure.
+ */
+
+On the above, ``struct`` is used to mean structs. You can also use ``union``
+and ``enum`` to describe unions and enums. ``argument`` is used
+to mean struct and union member names as well as enumerations in an enum.
+
+The brief description following the structure name may span multiple lines, and
+ends with a member description, a blank comment line, or the end of the
+comment block.
+
+The kernel-doc data structure comments describe each member of the structure,
+in order, with the member descriptions.
+
+
Highlights and cross-references
-------------------------------
@@ -331,30 +355,6 @@ cross-references.
For further details, please refer to the `Sphinx C Domain`_ documentation.
-Structure, union, and enumeration documentation
------------------------------------------------
-
-The general format of a struct, union, and enum kernel-doc comment is::
-
- /**
- * struct struct_name - Brief description.
- * @member_name: Description of member member_name.
- *
- * Description of the structure.
- */
-
-Below, "struct" is used to mean structs, unions and enums, and "member" is used
-to mean struct and union members as well as enumerations in an enum.
-
-The brief description following the structure name may span multiple lines, and
-ends with a ``@member:`` description, a blank comment line, or the end of the
-comment block.
-
-The kernel-doc data structure comments describe each member of the structure, in
-order, with the ``@member:`` descriptions. The ``@member:`` descriptions must
-begin on the very next line following the opening brief function description
-line, with no intervening blank comment lines. The ``@member:`` descriptions may
-span multiple lines. The continuation lines may contain indentation.
In-line member documentation comments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--
2.14.3
^ permalink raw reply related [flat|nested] 28+ messages in thread* [PATCH v4 05/18] docs: kernel-doc.rst: improve typedef documentation
2017-12-18 12:30 [PATCH v4 00/18] kernel-doc: add supported to document nested structs Mauro Carvalho Chehab
` (3 preceding siblings ...)
2017-12-18 12:30 ` [PATCH v4 04/18] docs: kernel-doc.rst: improve structs chapter Mauro Carvalho Chehab
@ 2017-12-18 12:30 ` Mauro Carvalho Chehab
2017-12-18 12:30 ` [PATCH v4 06/18] docs: kernel-doc.rst: add documentation about man pages Mauro Carvalho Chehab
` (13 subsequent siblings)
18 siblings, 0 replies; 28+ messages in thread
From: Mauro Carvalho Chehab @ 2017-12-18 12:30 UTC (permalink / raw)
To: Linux Media Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab,
Linux Doc Mailing List, Tom Saeger
Add documentation about typedefs for function prototypes and
move it to happen earlier.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/doc-guide/kernel-doc.rst | 32 ++++++++++++++++++++++----------
1 file changed, 22 insertions(+), 10 deletions(-)
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index e3e82f8f4de5..b178857866f8 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -282,6 +282,28 @@ The kernel-doc data structure comments describe each member of the structure,
in order, with the member descriptions.
+Typedef documentation
+---------------------
+
+The general format of a typedef kernel-doc comment is::
+
+ /**
+ * typedef type_name - Brief description.
+ *
+ * Description of the type.
+ */
+
+Typedefs with function prototypes can also be documented::
+
+ /**
+ * typedef type_name - Brief description.
+ * @arg1: description of arg1
+ * @arg2: description of arg2
+ *
+ * Description of the type.
+ */
+ typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);
+
Highlights and cross-references
-------------------------------
@@ -384,16 +406,6 @@ on a line of their own, like all other kernel-doc comments::
int foobar;
}
-Typedef documentation
----------------------
-
-The general format of a typedef kernel-doc comment is::
-
- /**
- * typedef type_name - Brief description.
- *
- * Description of the type.
- */
Overview documentation comments
-------------------------------
--
2.14.3
^ permalink raw reply related [flat|nested] 28+ messages in thread* [PATCH v4 06/18] docs: kernel-doc.rst: add documentation about man pages
2017-12-18 12:30 [PATCH v4 00/18] kernel-doc: add supported to document nested structs Mauro Carvalho Chehab
` (4 preceding siblings ...)
2017-12-18 12:30 ` [PATCH v4 05/18] docs: kernel-doc.rst: improve typedef documentation Mauro Carvalho Chehab
@ 2017-12-18 12:30 ` Mauro Carvalho Chehab
2017-12-18 12:30 ` [PATCH v4 07/18] docs: get rid of kernel-doc-nano-HOWTO.txt Mauro Carvalho Chehab
` (12 subsequent siblings)
18 siblings, 0 replies; 28+ messages in thread
From: Mauro Carvalho Chehab @ 2017-12-18 12:30 UTC (permalink / raw)
To: Linux Media Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab,
Linux Doc Mailing List, Tom Saeger
kernel-doc-nano-HOWTO.txt has a chapter about man pages
production. While we don't have a working "make manpages"
target, add it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/doc-guide/kernel-doc.rst | 34 ++++++++++++++++++++++++++++++++++
1 file changed, 34 insertions(+)
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index b178857866f8..14c226e8154f 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -452,3 +452,37 @@ file.
Data structures visible in kernel include files should also be documented using
kernel-doc formatted comments.
+
+How to use kernel-doc to generate man pages
+-------------------------------------------
+
+If you just want to use kernel-doc to generate man pages you can do this
+from the Kernel git tree::
+
+ $ scripts/kernel-doc -man $(git grep -l '/\*\*' |grep -v Documentation/) | ./split-man.pl /tmp/man
+
+Using the small ``split-man.pl`` script below::
+
+
+ #!/usr/bin/perl
+
+ if ($#ARGV < 0) {
+ die "where do I put the results?\n";
+ }
+
+ mkdir $ARGV[0],0777;
+ $state = 0;
+ while (<STDIN>) {
+ if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) {
+ if ($state == 1) { close OUT }
+ $state = 1;
+ $fn = "$ARGV[0]/$1.9";
+ print STDERR "Creating $fn\n";
+ open OUT, ">$fn" or die "can't open $fn: $!\n";
+ print OUT $_;
+ } elsif ($state != 0) {
+ print OUT $_;
+ }
+ }
+
+ close OUT;
--
2.14.3
^ permalink raw reply related [flat|nested] 28+ messages in thread* [PATCH v4 07/18] docs: get rid of kernel-doc-nano-HOWTO.txt
2017-12-18 12:30 [PATCH v4 00/18] kernel-doc: add supported to document nested structs Mauro Carvalho Chehab
` (5 preceding siblings ...)
2017-12-18 12:30 ` [PATCH v4 06/18] docs: kernel-doc.rst: add documentation about man pages Mauro Carvalho Chehab
@ 2017-12-18 12:30 ` Mauro Carvalho Chehab
2017-12-18 12:30 ` [PATCH v4 08/18] scripts: kernel-doc: get rid of unused output formats Mauro Carvalho Chehab
` (11 subsequent siblings)
18 siblings, 0 replies; 28+ messages in thread
From: Mauro Carvalho Chehab @ 2017-12-18 12:30 UTC (permalink / raw)
To: Linux Media Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Linux Doc Mailing List
Everything there is already described at
Documentation/doc-guide/kernel-doc.rst. So, there's no reason why
to keep it anymore.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/00-INDEX | 2 -
Documentation/kernel-doc-nano-HOWTO.txt | 322 --------------------------------
scripts/kernel-doc | 2 +-
3 files changed, 1 insertion(+), 325 deletions(-)
delete mode 100644 Documentation/kernel-doc-nano-HOWTO.txt
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 3bec49c33bbb..aca4f00ec69b 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -228,8 +228,6 @@ isdn/
- directory with info on the Linux ISDN support, and supported cards.
kbuild/
- directory with info about the kernel build process.
-kernel-doc-nano-HOWTO.txt
- - outdated info about kernel-doc documentation.
kdump/
- directory with mini HowTo on getting the crash dump code to work.
doc-guide/
diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt
deleted file mode 100644
index c23e2c5ab80d..000000000000
--- a/Documentation/kernel-doc-nano-HOWTO.txt
+++ /dev/null
@@ -1,322 +0,0 @@
-NOTE: this document is outdated and will eventually be removed. See
-Documentation/doc-guide/ for current information.
-
-kernel-doc nano-HOWTO
-=====================
-
-How to format kernel-doc comments
----------------------------------
-
-In order to provide embedded, 'C' friendly, easy to maintain,
-but consistent and extractable documentation of the functions and
-data structures in the Linux kernel, the Linux kernel has adopted
-a consistent style for documenting functions and their parameters,
-and structures and their members.
-
-The format for this documentation is called the kernel-doc format.
-It is documented in this Documentation/kernel-doc-nano-HOWTO.txt file.
-
-This style embeds the documentation within the source files, using
-a few simple conventions. The scripts/kernel-doc perl script, the
-Documentation/sphinx/kerneldoc.py Sphinx extension and other tools understand
-these conventions, and are used to extract this embedded documentation
-into various documents.
-
-In order to provide good documentation of kernel functions and data
-structures, please use the following conventions to format your
-kernel-doc comments in Linux kernel source.
-
-We definitely need kernel-doc formatted documentation for functions
-that are exported to loadable modules using EXPORT_SYMBOL.
-
-We also look to provide kernel-doc formatted documentation for
-functions externally visible to other kernel files (not marked
-"static").
-
-We also recommend providing kernel-doc formatted documentation
-for private (file "static") routines, for consistency of kernel
-source code layout. But this is lower priority and at the
-discretion of the MAINTAINER of that kernel source file.
-
-Data structures visible in kernel include files should also be
-documented using kernel-doc formatted comments.
-
-The opening comment mark "/**" is reserved for kernel-doc comments.
-Only comments so marked will be considered by the kernel-doc scripts,
-and any comment so marked must be in kernel-doc format. Do not use
-"/**" to be begin a comment block unless the comment block contains
-kernel-doc formatted comments. The closing comment marker for
-kernel-doc comments can be either "*/" or "**/", but "*/" is
-preferred in the Linux kernel tree.
-
-Kernel-doc comments should be placed just before the function
-or data structure being described.
-
-Example kernel-doc function comment:
-
-/**
- * foobar() - short function description of foobar
- * @arg1: Describe the first argument to foobar.
- * @arg2: Describe the second argument to foobar.
- * One can provide multiple line descriptions
- * for arguments.
- *
- * A longer description, with more discussion of the function foobar()
- * that might be useful to those using or modifying it. Begins with
- * empty comment line, and may include additional embedded empty
- * comment lines.
- *
- * The longer description can have multiple paragraphs.
- *
- * Return: Describe the return value of foobar.
- */
-
-The short description following the subject can span multiple lines
-and ends with an @argument description, an empty line or the end of
-the comment block.
-
-The @argument descriptions must begin on the very next line following
-this opening short function description line, with no intervening
-empty comment lines.
-
-If a function parameter is "..." (varargs), it should be listed in
-kernel-doc notation as:
- * @...: description
-
-The return value, if any, should be described in a dedicated section
-named "Return".
-
-Example kernel-doc data structure comment.
-
-/**
- * struct blah - the basic blah structure
- * @mem1: describe the first member of struct blah
- * @mem2: describe the second member of struct blah,
- * perhaps with more lines and words.
- *
- * Longer description of this structure.
- */
-
-The kernel-doc function comments describe each parameter to the
-function, in order, with the @name lines.
-
-The kernel-doc data structure comments describe each structure member
-in the data structure, with the @name lines.
-
-The longer description formatting is "reflowed", losing your line
-breaks. So presenting carefully formatted lists within these
-descriptions won't work so well; derived documentation will lose
-the formatting.
-
-See the section below "How to add extractable documentation to your
-source files" for more details and notes on how to format kernel-doc
-comments.
-
-Components of the kernel-doc system
------------------------------------
-
-Many places in the source tree have extractable documentation in the
-form of block comments above functions. The components of this system
-are:
-
-- scripts/kernel-doc
-
- This is a perl script that hunts for the block comments and can mark
- them up directly into DocBook, ReST, man, text, and HTML. (No, not
- texinfo.)
-
-- scripts/docproc.c
-
- This is a program for converting SGML template files into SGML
- files. When a file is referenced it is searched for symbols
- exported (EXPORT_SYMBOL), to be able to distinguish between internal
- and external functions.
- It invokes kernel-doc, giving it the list of functions that
- are to be documented.
- Additionally it is used to scan the SGML template files to locate
- all the files referenced herein. This is used to generate dependency
- information as used by make.
-
-- Makefile
-
- The targets 'xmldocs', 'latexdocs', 'pdfdocs', 'epubdocs'and 'htmldocs'
- are used to build XML DocBook files, LaTeX files, PDF files,
- ePub files and html files in Documentation/.
-
-How to extract the documentation
---------------------------------
-
-If you just want to read the ready-made books on the various
-subsystems, just type 'make epubdocs', or 'make pdfdocs', or 'make htmldocs',
-depending on your preference. If you would rather read a different format,
-you can type 'make xmldocs' and then use DocBook tools to convert
-Documentation/output/*.xml to a format of your choice (for example,
-'db2html ...' if 'make htmldocs' was not defined).
-
-If you want to see man pages instead, you can do this:
-
-$ cd linux
-$ scripts/kernel-doc -man $(find -name '*.c') | split-man.pl /tmp/man
-$ scripts/kernel-doc -man $(find -name '*.h') | split-man.pl /tmp/man
-
-Here is split-man.pl:
-
--->
-#!/usr/bin/perl
-
-if ($#ARGV < 0) {
- die "where do I put the results?\n";
-}
-
-mkdir $ARGV[0],0777;
-$state = 0;
-while (<STDIN>) {
- if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) {
- if ($state == 1) { close OUT }
- $state = 1;
- $fn = "$ARGV[0]/$1.9";
- print STDERR "Creating $fn\n";
- open OUT, ">$fn" or die "can't open $fn: $!\n";
- print OUT $_;
- } elsif ($state != 0) {
- print OUT $_;
- }
-}
-
-close OUT;
-<--
-
-If you just want to view the documentation for one function in one
-file, you can do this:
-
-$ scripts/kernel-doc -man -function fn file | nroff -man | less
-
-or this:
-
-$ scripts/kernel-doc -text -function fn file
-
-
-How to add extractable documentation to your source files
----------------------------------------------------------
-
-The format of the block comment is like this:
-
-/**
- * function_name(:)? (- short description)?
-(* @parameterx(space)*: (description of parameter x)?)*
-(* a blank line)?
- * (Description:)? (Description of function)?
- * (section header: (section description)? )*
-(*)?*/
-
-All "description" text can span multiple lines, although the
-function_name & its short description are traditionally on a single line.
-Description text may also contain blank lines (i.e., lines that contain
-only a "*").
-
-"section header:" names must be unique per function (or struct,
-union, typedef, enum).
-
-Use the section header "Return" for sections describing the return value
-of a function.
-
-Avoid putting a spurious blank line after the function name, or else the
-description will be repeated!
-
-All descriptive text is further processed, scanning for the following special
-patterns, which are highlighted appropriately.
-
-'funcname()' - function
-'$ENVVAR' - environment variable
-'&struct_name' - name of a structure (up to two words including 'struct')
-'@parameter' - name of a parameter
-'%CONST' - name of a constant.
-
-NOTE 1: The multi-line descriptive text you provide does *not* recognize
-line breaks, so if you try to format some text nicely, as in:
-
- Return:
- 0 - cool
- 1 - invalid arg
- 2 - out of memory
-
-this will all run together and produce:
-
- Return: 0 - cool 1 - invalid arg 2 - out of memory
-
-NOTE 2: If the descriptive text you provide has lines that begin with
-some phrase followed by a colon, each of those phrases will be taken as
-a new section heading, which means you should similarly try to avoid text
-like:
-
- Return:
- 0: cool
- 1: invalid arg
- 2: out of memory
-
-every line of which would start a new section. Again, probably not
-what you were after.
-
-Take a look around the source tree for examples.
-
-
-kernel-doc for structs, unions, enums, and typedefs
----------------------------------------------------
-
-Beside functions you can also write documentation for structs, unions,
-enums and typedefs. Instead of the function name you must write the name
-of the declaration; the struct/union/enum/typedef must always precede
-the name. Nesting of declarations is not supported.
-Use the argument mechanism to document members or constants.
-
-Inside a struct description, you can use the "private:" and "public:"
-comment tags. Structure fields that are inside a "private:" area
-are not listed in the generated output documentation. The "private:"
-and "public:" tags must begin immediately following a "/*" comment
-marker. They may optionally include comments between the ":" and the
-ending "*/" marker.
-
-Example:
-
-/**
- * struct my_struct - short description
- * @a: first member
- * @b: second member
- *
- * Longer description
- */
-struct my_struct {
- int a;
- int b;
-/* private: internal use only */
- int c;
-};
-
-
-Including documentation blocks in source files
-----------------------------------------------
-
-To facilitate having source code and comments close together, you can
-include kernel-doc documentation blocks that are free-form comments
-instead of being kernel-doc for functions, structures, unions,
-enums, or typedefs. This could be used for something like a
-theory of operation for a driver or library code, for example.
-
-This is done by using a DOC: section keyword with a section title. E.g.:
-
-/**
- * DOC: Theory of Operation
- *
- * The whizbang foobar is a dilly of a gizmo. It can do whatever you
- * want it to do, at any time. It reads your mind. Here's how it works.
- *
- * foo bar splat
- *
- * The only drawback to this gizmo is that is can sometimes damage
- * hardware, software, or its subject(s).
- */
-
-DOC: sections are used in ReST files.
-
-Tim.
-*/ <twaugh@redhat.com>
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 675c525ec5b9..bed74e9bc141 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -48,7 +48,7 @@ Read C language source or header FILEs, extract embedded documentation comments,
and print formatted documentation to standard output.
The documentation comments are identified by "/**" opening comment mark. See
-Documentation/kernel-doc-nano-HOWTO.txt for the documentation comment syntax.
+Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
Output format selection (mutually exclusive):
-docbook Output DocBook format.
--
2.14.3
^ permalink raw reply related [flat|nested] 28+ messages in thread* [PATCH v4 08/18] scripts: kernel-doc: get rid of unused output formats
2017-12-18 12:30 [PATCH v4 00/18] kernel-doc: add supported to document nested structs Mauro Carvalho Chehab
` (6 preceding siblings ...)
2017-12-18 12:30 ` [PATCH v4 07/18] docs: get rid of kernel-doc-nano-HOWTO.txt Mauro Carvalho Chehab
@ 2017-12-18 12:30 ` Mauro Carvalho Chehab
2017-12-18 12:30 ` [PATCH v4 09/18] scripts: kernel-doc: improve argument handling Mauro Carvalho Chehab
` (10 subsequent siblings)
18 siblings, 0 replies; 28+ messages in thread
From: Mauro Carvalho Chehab @ 2017-12-18 12:30 UTC (permalink / raw)
To: Linux Media Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Linux Doc Mailing List
Since there isn't any docbook code anymore upstream,
we can get rid of several output formats:
- docbook/xml, html, html5 and list formats were used by
the old build system;
- As ReST is text, there's not much sense on outputting
on a different text format.
After this patch, only man and rst output formats are
supported.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Acked-by: Jani Nikula <jani.nikula@intel.com>
---
scripts/kernel-doc | 1183 +---------------------------------------------------
1 file changed, 4 insertions(+), 1179 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index bed74e9bc141..c8ad05eb3e5e 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -51,13 +51,8 @@ The documentation comments are identified by "/**" opening comment mark. See
Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
Output format selection (mutually exclusive):
- -docbook Output DocBook format.
- -html Output HTML format.
- -html5 Output HTML5 format.
- -list Output symbol list format. This is for use by docproc.
-man Output troff manual page format. This is the default.
-rst Output reStructuredText format.
- -text Output plain text format.
-none Do not output documentation, only warnings.
Output selection (mutually exclusive):
@@ -225,84 +220,11 @@ my $type_typedef = '\&(typedef\s*([_\w]+))';
my $type_union = '\&(union\s*([_\w]+))';
my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';
my $type_fallback = '\&([_\w]+)';
-my $type_enum_xml = '\&(enum\s*([_\w]+))';
-my $type_struct_xml = '\&(struct\s*([_\w]+))';
-my $type_typedef_xml = '\&(typedef\s*([_\w]+))';
-my $type_union_xml = '\&(union\s*([_\w]+))';
-my $type_member_xml = '\&([_\w]+)(\.|-\>)([_\w]+)';
-my $type_fallback_xml = '\&([_\w]+)';
my $type_member_func = $type_member . '\(\)';
# Output conversion substitutions.
# One for each output format
-# these work fairly well
-my @highlights_html = (
- [$type_constant, "<i>\$1</i>"],
- [$type_constant2, "<i>\$1</i>"],
- [$type_func, "<b>\$1</b>"],
- [$type_enum_xml, "<i>\$1</i>"],
- [$type_struct_xml, "<i>\$1</i>"],
- [$type_typedef_xml, "<i>\$1</i>"],
- [$type_union_xml, "<i>\$1</i>"],
- [$type_env, "<b><i>\$1</i></b>"],
- [$type_param, "<tt><b>\$1</b></tt>"],
- [$type_member_xml, "<tt><i>\$1</i>\$2\$3</tt>"],
- [$type_fallback_xml, "<i>\$1</i>"]
- );
-my $local_lt = "\\\\\\\\lt:";
-my $local_gt = "\\\\\\\\gt:";
-my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>"
-
-# html version 5
-my @highlights_html5 = (
- [$type_constant, "<span class=\"const\">\$1</span>"],
- [$type_constant2, "<span class=\"const\">\$1</span>"],
- [$type_func, "<span class=\"func\">\$1</span>"],
- [$type_enum_xml, "<span class=\"enum\">\$1</span>"],
- [$type_struct_xml, "<span class=\"struct\">\$1</span>"],
- [$type_typedef_xml, "<span class=\"typedef\">\$1</span>"],
- [$type_union_xml, "<span class=\"union\">\$1</span>"],
- [$type_env, "<span class=\"env\">\$1</span>"],
- [$type_param, "<span class=\"param\">\$1</span>]"],
- [$type_member_xml, "<span class=\"literal\"><span class=\"struct\">\$1</span>\$2<span class=\"member\">\$3</span></span>"],
- [$type_fallback_xml, "<span class=\"struct\">\$1</span>"]
- );
-my $blankline_html5 = $local_lt . "br /" . $local_gt;
-
-# XML, docbook format
-my @highlights_xml = (
- ["([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>"],
- [$type_constant, "<constant>\$1</constant>"],
- [$type_constant2, "<constant>\$1</constant>"],
- [$type_enum_xml, "<type>\$1</type>"],
- [$type_struct_xml, "<structname>\$1</structname>"],
- [$type_typedef_xml, "<type>\$1</type>"],
- [$type_union_xml, "<structname>\$1</structname>"],
- [$type_param, "<parameter>\$1</parameter>"],
- [$type_func, "<function>\$1</function>"],
- [$type_env, "<envar>\$1</envar>"],
- [$type_member_xml, "<literal><structname>\$1</structname>\$2<structfield>\$3</structfield></literal>"],
- [$type_fallback_xml, "<structname>\$1</structname>"]
- );
-my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n";
-
-# gnome, docbook format
-my @highlights_gnome = (
- [$type_constant, "<replaceable class=\"option\">\$1</replaceable>"],
- [$type_constant2, "<replaceable class=\"option\">\$1</replaceable>"],
- [$type_func, "<function>\$1</function>"],
- [$type_enum, "<type>\$1</type>"],
- [$type_struct, "<structname>\$1</structname>"],
- [$type_typedef, "<type>\$1</type>"],
- [$type_union, "<structname>\$1</structname>"],
- [$type_env, "<envar>\$1</envar>"],
- [$type_param, "<parameter>\$1</parameter>" ],
- [$type_member, "<literal><structname>\$1</structname>\$2<structfield>\$3</structfield></literal>"],
- [$type_fallback, "<structname>\$1</structname>"]
- );
-my $blankline_gnome = "</para><para>\n";
-
# these are pretty rough
my @highlights_man = (
[$type_constant, "\$1"],
@@ -318,21 +240,6 @@ my @highlights_man = (
);
my $blankline_man = "";
-# text-mode
-my @highlights_text = (
- [$type_constant, "\$1"],
- [$type_constant2, "\$1"],
- [$type_func, "\$1"],
- [$type_enum, "\$1"],
- [$type_struct, "\$1"],
- [$type_typedef, "\$1"],
- [$type_union, "\$1"],
- [$type_param, "\$1"],
- [$type_member, "\$1\$2\$3"],
- [$type_fallback, "\$1"]
- );
-my $blankline_text = "";
-
# rst-mode
my @highlights_rst = (
[$type_constant, "``\$1``"],
@@ -352,21 +259,6 @@ my @highlights_rst = (
);
my $blankline_rst = "\n";
-# list mode
-my @highlights_list = (
- [$type_constant, "\$1"],
- [$type_constant2, "\$1"],
- [$type_func, "\$1"],
- [$type_enum, "\$1"],
- [$type_struct, "\$1"],
- [$type_typedef, "\$1"],
- [$type_union, "\$1"],
- [$type_param, "\$1"],
- [$type_member, "\$1"],
- [$type_fallback, "\$1"]
- );
-my $blankline_list = "";
-
# read arguments
if ($#ARGV == -1) {
usage();
@@ -501,38 +393,14 @@ reset_state();
while ($ARGV[0] =~ m/^-(.*)/) {
my $cmd = shift @ARGV;
- if ($cmd eq "-html") {
- $output_mode = "html";
- @highlights = @highlights_html;
- $blankline = $blankline_html;
- } elsif ($cmd eq "-html5") {
- $output_mode = "html5";
- @highlights = @highlights_html5;
- $blankline = $blankline_html5;
- } elsif ($cmd eq "-man") {
+ if ($cmd eq "-man") {
$output_mode = "man";
@highlights = @highlights_man;
$blankline = $blankline_man;
- } elsif ($cmd eq "-text") {
- $output_mode = "text";
- @highlights = @highlights_text;
- $blankline = $blankline_text;
} elsif ($cmd eq "-rst") {
$output_mode = "rst";
@highlights = @highlights_rst;
$blankline = $blankline_rst;
- } elsif ($cmd eq "-docbook") {
- $output_mode = "xml";
- @highlights = @highlights_xml;
- $blankline = $blankline_xml;
- } elsif ($cmd eq "-list") {
- $output_mode = "list";
- @highlights = @highlights_list;
- $blankline = $blankline_list;
- } elsif ($cmd eq "-gnome") {
- $output_mode = "gnome";
- @highlights = @highlights_gnome;
- $blankline = $blankline_gnome;
} elsif ($cmd eq "-none") {
$output_mode = "none";
} elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
@@ -670,22 +538,11 @@ sub output_highlight {
# confess "output_highlight got called with no args?\n";
# }
- if ($output_mode eq "html" || $output_mode eq "html5" ||
- $output_mode eq "xml") {
- $contents = local_unescape($contents);
- # convert data read & converted thru xml_escape() into &xyz; format:
- $contents =~ s/\\\\\\/\&/g;
- }
# print STDERR "contents b4:$contents\n";
eval $dohighlight;
die $@ if $@;
# print STDERR "contents af:$contents\n";
-# strip whitespaces when generating html5
- if ($output_mode eq "html5") {
- $contents =~ s/^\s+//;
- $contents =~ s/\s+$//;
- }
foreach $line (split "\n", $contents) {
if (! $output_preformatted) {
$line =~ s/^\s*//;
@@ -706,817 +563,6 @@ sub output_highlight {
}
}
-# output sections in html
-sub output_section_html(%) {
- my %args = %{$_[0]};
- my $section;
-
- foreach $section (@{$args{'sectionlist'}}) {
- print "<h3>$section</h3>\n";
- print "<blockquote>\n";
- output_highlight($args{'sections'}{$section});
- print "</blockquote>\n";
- }
-}
-
-# output enum in html
-sub output_enum_html(%) {
- my %args = %{$_[0]};
- my ($parameter);
- my $count;
- print "<h2>enum " . $args{'enum'} . "</h2>\n";
-
- print "<b>enum " . $args{'enum'} . "</b> {<br>\n";
- $count = 0;
- foreach $parameter (@{$args{'parameterlist'}}) {
- print " <b>" . $parameter . "</b>";
- if ($count != $#{$args{'parameterlist'}}) {
- $count++;
- print ",\n";
- }
- print "<br>";
- }
- print "};<br>\n";
-
- print "<h3>Constants</h3>\n";
- print "<dl>\n";
- foreach $parameter (@{$args{'parameterlist'}}) {
- print "<dt><b>" . $parameter . "</b>\n";
- print "<dd>";
- output_highlight($args{'parameterdescs'}{$parameter});
- }
- print "</dl>\n";
- output_section_html(@_);
- print "<hr>\n";
-}
-
-# output typedef in html
-sub output_typedef_html(%) {
- my %args = %{$_[0]};
- my ($parameter);
- my $count;
- print "<h2>typedef " . $args{'typedef'} . "</h2>\n";
-
- print "<b>typedef " . $args{'typedef'} . "</b>\n";
- output_section_html(@_);
- print "<hr>\n";
-}
-
-# output struct in html
-sub output_struct_html(%) {
- my %args = %{$_[0]};
- my ($parameter);
-
- print "<h2>" . $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "</h2>\n";
- print "<b>" . $args{'type'} . " " . $args{'struct'} . "</b> {<br>\n";
- foreach $parameter (@{$args{'parameterlist'}}) {
- if ($parameter =~ /^#/) {
- print "$parameter<br>\n";
- next;
- }
- my $parameter_name = $parameter;
- $parameter_name =~ s/\[.*//;
-
- ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
- $type = $args{'parametertypes'}{$parameter};
- if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
- # pointer-to-function
- print " <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n";
- } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
- # bitfield
- print " <i>$1</i> <b>$parameter</b>$2;<br>\n";
- } else {
- print " <i>$type</i> <b>$parameter</b>;<br>\n";
- }
- }
- print "};<br>\n";
-
- print "<h3>Members</h3>\n";
- print "<dl>\n";
- foreach $parameter (@{$args{'parameterlist'}}) {
- ($parameter =~ /^#/) && next;
-
- my $parameter_name = $parameter;
- $parameter_name =~ s/\[.*//;
-
- ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
- print "<dt><b>" . $parameter . "</b>\n";
- print "<dd>";
- output_highlight($args{'parameterdescs'}{$parameter_name});
- }
- print "</dl>\n";
- output_section_html(@_);
- print "<hr>\n";
-}
-
-# output function in html
-sub output_function_html(%) {
- my %args = %{$_[0]};
- my ($parameter, $section);
- my $count;
-
- print "<h2>" . $args{'function'} . " - " . $args{'purpose'} . "</h2>\n";
- print "<i>" . $args{'functiontype'} . "</i>\n";
- print "<b>" . $args{'function'} . "</b>\n";
- print "(";
- $count = 0;
- foreach $parameter (@{$args{'parameterlist'}}) {
- $type = $args{'parametertypes'}{$parameter};
- if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
- # pointer-to-function
- print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";
- } else {
- print "<i>" . $type . "</i> <b>" . $parameter . "</b>";
- }
- if ($count != $#{$args{'parameterlist'}}) {
- $count++;
- print ",\n";
- }
- }
- print ")\n";
-
- print "<h3>Arguments</h3>\n";
- print "<dl>\n";
- foreach $parameter (@{$args{'parameterlist'}}) {
- my $parameter_name = $parameter;
- $parameter_name =~ s/\[.*//;
-
- ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
- print "<dt><b>" . $parameter . "</b>\n";
- print "<dd>";
- output_highlight($args{'parameterdescs'}{$parameter_name});
- }
- print "</dl>\n";
- output_section_html(@_);
- print "<hr>\n";
-}
-
-# output DOC: block header in html
-sub output_blockhead_html(%) {
- my %args = %{$_[0]};
- my ($parameter, $section);
- my $count;
-
- foreach $section (@{$args{'sectionlist'}}) {
- print "<h3>$section</h3>\n";
- print "<ul>\n";
- output_highlight($args{'sections'}{$section});
- print "</ul>\n";
- }
- print "<hr>\n";
-}
-
-# output sections in html5
-sub output_section_html5(%) {
- my %args = %{$_[0]};
- my $section;
-
- foreach $section (@{$args{'sectionlist'}}) {
- print "<section>\n";
- print "<h1>$section</h1>\n";
- print "<p>\n";
- output_highlight($args{'sections'}{$section});
- print "</p>\n";
- print "</section>\n";
- }
-}
-
-# output enum in html5
-sub output_enum_html5(%) {
- my %args = %{$_[0]};
- my ($parameter);
- my $count;
- my $html5id;
-
- $html5id = $args{'enum'};
- $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
- print "<article class=\"enum\" id=\"enum:". $html5id . "\">";
- print "<h1>enum " . $args{'enum'} . "</h1>\n";
- print "<ol class=\"code\">\n";
- print "<li>";
- print "<span class=\"keyword\">enum</span> ";
- print "<span class=\"identifier\">" . $args{'enum'} . "</span> {";
- print "</li>\n";
- $count = 0;
- foreach $parameter (@{$args{'parameterlist'}}) {
- print "<li class=\"indent\">";
- print "<span class=\"param\">" . $parameter . "</span>";
- if ($count != $#{$args{'parameterlist'}}) {
- $count++;
- print ",";
- }
- print "</li>\n";
- }
- print "<li>};</li>\n";
- print "</ol>\n";
-
- print "<section>\n";
- print "<h1>Constants</h1>\n";
- print "<dl>\n";
- foreach $parameter (@{$args{'parameterlist'}}) {
- print "<dt>" . $parameter . "</dt>\n";
- print "<dd>";
- output_highlight($args{'parameterdescs'}{$parameter});
- print "</dd>\n";
- }
- print "</dl>\n";
- print "</section>\n";
- output_section_html5(@_);
- print "</article>\n";
-}
-
-# output typedef in html5
-sub output_typedef_html5(%) {
- my %args = %{$_[0]};
- my ($parameter);
- my $count;
- my $html5id;
-
- $html5id = $args{'typedef'};
- $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
- print "<article class=\"typedef\" id=\"typedef:" . $html5id . "\">\n";
- print "<h1>typedef " . $args{'typedef'} . "</h1>\n";
-
- print "<ol class=\"code\">\n";
- print "<li>";
- print "<span class=\"keyword\">typedef</span> ";
- print "<span class=\"identifier\">" . $args{'typedef'} . "</span>";
- print "</li>\n";
- print "</ol>\n";
- output_section_html5(@_);
- print "</article>\n";
-}
-
-# output struct in html5
-sub output_struct_html5(%) {
- my %args = %{$_[0]};
- my ($parameter);
- my $html5id;
-
- $html5id = $args{'struct'};
- $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
- print "<article class=\"struct\" id=\"struct:" . $html5id . "\">\n";
- print "<hgroup>\n";
- print "<h1>" . $args{'type'} . " " . $args{'struct'} . "</h1>";
- print "<h2>". $args{'purpose'} . "</h2>\n";
- print "</hgroup>\n";
- print "<ol class=\"code\">\n";
- print "<li>";
- print "<span class=\"type\">" . $args{'type'} . "</span> ";
- print "<span class=\"identifier\">" . $args{'struct'} . "</span> {";
- print "</li>\n";
- foreach $parameter (@{$args{'parameterlist'}}) {
- print "<li class=\"indent\">";
- if ($parameter =~ /^#/) {
- print "<span class=\"param\">" . $parameter ."</span>\n";
- print "</li>\n";
- next;
- }
- my $parameter_name = $parameter;
- $parameter_name =~ s/\[.*//;
-
- ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
- $type = $args{'parametertypes'}{$parameter};
- if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
- # pointer-to-function
- print "<span class=\"type\">$1</span> ";
- print "<span class=\"param\">$parameter</span>";
- print "<span class=\"type\">)</span> ";
- print "(<span class=\"args\">$2</span>);";
- } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
- # bitfield
- print "<span class=\"type\">$1</span> ";
- print "<span class=\"param\">$parameter</span>";
- print "<span class=\"bits\">$2</span>;";
- } else {
- print "<span class=\"type\">$type</span> ";
- print "<span class=\"param\">$parameter</span>;";
- }
- print "</li>\n";
- }
- print "<li>};</li>\n";
- print "</ol>\n";
-
- print "<section>\n";
- print "<h1>Members</h1>\n";
- print "<dl>\n";
- foreach $parameter (@{$args{'parameterlist'}}) {
- ($parameter =~ /^#/) && next;
-
- my $parameter_name = $parameter;
- $parameter_name =~ s/\[.*//;
-
- ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
- print "<dt>" . $parameter . "</dt>\n";
- print "<dd>";
- output_highlight($args{'parameterdescs'}{$parameter_name});
- print "</dd>\n";
- }
- print "</dl>\n";
- print "</section>\n";
- output_section_html5(@_);
- print "</article>\n";
-}
-
-# output function in html5
-sub output_function_html5(%) {
- my %args = %{$_[0]};
- my ($parameter, $section);
- my $count;
- my $html5id;
-
- $html5id = $args{'function'};
- $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
- print "<article class=\"function\" id=\"func:". $html5id . "\">\n";
- print "<hgroup>\n";
- print "<h1>" . $args{'function'} . "</h1>";
- print "<h2>" . $args{'purpose'} . "</h2>\n";
- print "</hgroup>\n";
- print "<ol class=\"code\">\n";
- print "<li>";
- print "<span class=\"type\">" . $args{'functiontype'} . "</span> ";
- print "<span class=\"identifier\">" . $args{'function'} . "</span> (";
- print "</li>";
- $count = 0;
- foreach $parameter (@{$args{'parameterlist'}}) {
- print "<li class=\"indent\">";
- $type = $args{'parametertypes'}{$parameter};
- if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
- # pointer-to-function
- print "<span class=\"type\">$1</span> ";
- print "<span class=\"param\">$parameter</span>";
- print "<span class=\"type\">)</span> ";
- print "(<span class=\"args\">$2</span>)";
- } else {
- print "<span class=\"type\">$type</span> ";
- print "<span class=\"param\">$parameter</span>";
- }
- if ($count != $#{$args{'parameterlist'}}) {
- $count++;
- print ",";
- }
- print "</li>\n";
- }
- print "<li>)</li>\n";
- print "</ol>\n";
-
- print "<section>\n";
- print "<h1>Arguments</h1>\n";
- print "<p>\n";
- print "<dl>\n";
- foreach $parameter (@{$args{'parameterlist'}}) {
- my $parameter_name = $parameter;
- $parameter_name =~ s/\[.*//;
-
- ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
- print "<dt>" . $parameter . "</dt>\n";
- print "<dd>";
- output_highlight($args{'parameterdescs'}{$parameter_name});
- print "</dd>\n";
- }
- print "</dl>\n";
- print "</section>\n";
- output_section_html5(@_);
- print "</article>\n";
-}
-
-# output DOC: block header in html5
-sub output_blockhead_html5(%) {
- my %args = %{$_[0]};
- my ($parameter, $section);
- my $count;
- my $html5id;
-
- foreach $section (@{$args{'sectionlist'}}) {
- $html5id = $section;
- $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
- print "<article class=\"doc\" id=\"doc:". $html5id . "\">\n";
- print "<h1>$section</h1>\n";
- print "<p>\n";
- output_highlight($args{'sections'}{$section});
- print "</p>\n";
- }
- print "</article>\n";
-}
-
-sub output_section_xml(%) {
- my %args = %{$_[0]};
- my $section;
- # print out each section
- $lineprefix=" ";
- foreach $section (@{$args{'sectionlist'}}) {
- print "<refsect1>\n";
- print "<title>$section</title>\n";
- if ($section =~ m/EXAMPLE/i) {
- print "<informalexample><programlisting>\n";
- $output_preformatted = 1;
- } else {
- print "<para>\n";
- }
- output_highlight($args{'sections'}{$section});
- $output_preformatted = 0;
- if ($section =~ m/EXAMPLE/i) {
- print "</programlisting></informalexample>\n";
- } else {
- print "</para>\n";
- }
- print "</refsect1>\n";
- }
-}
-
-# output function in XML DocBook
-sub output_function_xml(%) {
- my %args = %{$_[0]};
- my ($parameter, $section);
- my $count;
- my $id;
-
- $id = "API-" . $args{'function'};
- $id =~ s/[^A-Za-z0-9]/-/g;
-
- print "<refentry id=\"$id\">\n";
- print "<refentryinfo>\n";
- print " <title>LINUX</title>\n";
- print " <productname>Kernel Hackers Manual</productname>\n";
- print " <date>$man_date</date>\n";
- print "</refentryinfo>\n";
- print "<refmeta>\n";
- print " <refentrytitle><phrase>" . $args{'function'} . "</phrase></refentrytitle>\n";
- print " <manvolnum>9</manvolnum>\n";
- print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
- print "</refmeta>\n";
- print "<refnamediv>\n";
- print " <refname>" . $args{'function'} . "</refname>\n";
- print " <refpurpose>\n";
- print " ";
- output_highlight ($args{'purpose'});
- print " </refpurpose>\n";
- print "</refnamediv>\n";
-
- print "<refsynopsisdiv>\n";
- print " <title>Synopsis</title>\n";
- print " <funcsynopsis><funcprototype>\n";
- print " <funcdef>" . $args{'functiontype'} . " ";
- print "<function>" . $args{'function'} . " </function></funcdef>\n";
-
- $count = 0;
- if ($#{$args{'parameterlist'}} >= 0) {
- foreach $parameter (@{$args{'parameterlist'}}) {
- $type = $args{'parametertypes'}{$parameter};
- if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
- # pointer-to-function
- print " <paramdef>$1<parameter>$parameter</parameter>)\n";
- print " <funcparams>$2</funcparams></paramdef>\n";
- } else {
- print " <paramdef>" . $type;
- print " <parameter>$parameter</parameter></paramdef>\n";
- }
- }
- } else {
- print " <void/>\n";
- }
- print " </funcprototype></funcsynopsis>\n";
- print "</refsynopsisdiv>\n";
-
- # print parameters
- print "<refsect1>\n <title>Arguments</title>\n";
- if ($#{$args{'parameterlist'}} >= 0) {
- print " <variablelist>\n";
- foreach $parameter (@{$args{'parameterlist'}}) {
- my $parameter_name = $parameter;
- $parameter_name =~ s/\[.*//;
- $type = $args{'parametertypes'}{$parameter};
-
- print " <varlistentry>\n <term><parameter>$type $parameter</parameter></term>\n";
- print " <listitem>\n <para>\n";
- $lineprefix=" ";
- output_highlight($args{'parameterdescs'}{$parameter_name});
- print " </para>\n </listitem>\n </varlistentry>\n";
- }
- print " </variablelist>\n";
- } else {
- print " <para>\n None\n </para>\n";
- }
- print "</refsect1>\n";
-
- output_section_xml(@_);
- print "</refentry>\n\n";
-}
-
-# output struct in XML DocBook
-sub output_struct_xml(%) {
- my %args = %{$_[0]};
- my ($parameter, $section);
- my $id;
-
- $id = "API-struct-" . $args{'struct'};
- $id =~ s/[^A-Za-z0-9]/-/g;
-
- print "<refentry id=\"$id\">\n";
- print "<refentryinfo>\n";
- print " <title>LINUX</title>\n";
- print " <productname>Kernel Hackers Manual</productname>\n";
- print " <date>$man_date</date>\n";
- print "</refentryinfo>\n";
- print "<refmeta>\n";
- print " <refentrytitle><phrase>" . $args{'type'} . " " . $args{'struct'} . "</phrase></refentrytitle>\n";
- print " <manvolnum>9</manvolnum>\n";
- print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
- print "</refmeta>\n";
- print "<refnamediv>\n";
- print " <refname>" . $args{'type'} . " " . $args{'struct'} . "</refname>\n";
- print " <refpurpose>\n";
- print " ";
- output_highlight ($args{'purpose'});
- print " </refpurpose>\n";
- print "</refnamediv>\n";
-
- print "<refsynopsisdiv>\n";
- print " <title>Synopsis</title>\n";
- print " <programlisting>\n";
- print $args{'type'} . " " . $args{'struct'} . " {\n";
- foreach $parameter (@{$args{'parameterlist'}}) {
- if ($parameter =~ /^#/) {
- my $prm = $parameter;
- # convert data read & converted thru xml_escape() into &xyz; format:
- # This allows us to have #define macros interspersed in a struct.
- $prm =~ s/\\\\\\/\&/g;
- print "$prm\n";
- next;
- }
-
- my $parameter_name = $parameter;
- $parameter_name =~ s/\[.*//;
-
- defined($args{'parameterdescs'}{$parameter_name}) || next;
- ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
- $type = $args{'parametertypes'}{$parameter};
- if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
- # pointer-to-function
- print " $1 $parameter) ($2);\n";
- } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
- # bitfield
- print " $1 $parameter$2;\n";
- } else {
- print " " . $type . " " . $parameter . ";\n";
- }
- }
- print "};";
- print " </programlisting>\n";
- print "</refsynopsisdiv>\n";
-
- print " <refsect1>\n";
- print " <title>Members</title>\n";
-
- if ($#{$args{'parameterlist'}} >= 0) {
- print " <variablelist>\n";
- foreach $parameter (@{$args{'parameterlist'}}) {
- ($parameter =~ /^#/) && next;
-
- my $parameter_name = $parameter;
- $parameter_name =~ s/\[.*//;
-
- defined($args{'parameterdescs'}{$parameter_name}) || next;
- ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
- $type = $args{'parametertypes'}{$parameter};
- print " <varlistentry>";
- print " <term><literal>$type $parameter</literal></term>\n";
- print " <listitem><para>\n";
- output_highlight($args{'parameterdescs'}{$parameter_name});
- print " </para></listitem>\n";
- print " </varlistentry>\n";
- }
- print " </variablelist>\n";
- } else {
- print " <para>\n None\n </para>\n";
- }
- print " </refsect1>\n";
-
- output_section_xml(@_);
-
- print "</refentry>\n\n";
-}
-
-# output enum in XML DocBook
-sub output_enum_xml(%) {
- my %args = %{$_[0]};
- my ($parameter, $section);
- my $count;
- my $id;
-
- $id = "API-enum-" . $args{'enum'};
- $id =~ s/[^A-Za-z0-9]/-/g;
-
- print "<refentry id=\"$id\">\n";
- print "<refentryinfo>\n";
- print " <title>LINUX</title>\n";
- print " <productname>Kernel Hackers Manual</productname>\n";
- print " <date>$man_date</date>\n";
- print "</refentryinfo>\n";
- print "<refmeta>\n";
- print " <refentrytitle><phrase>enum " . $args{'enum'} . "</phrase></refentrytitle>\n";
- print " <manvolnum>9</manvolnum>\n";
- print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
- print "</refmeta>\n";
- print "<refnamediv>\n";
- print " <refname>enum " . $args{'enum'} . "</refname>\n";
- print " <refpurpose>\n";
- print " ";
- output_highlight ($args{'purpose'});
- print " </refpurpose>\n";
- print "</refnamediv>\n";
-
- print "<refsynopsisdiv>\n";
- print " <title>Synopsis</title>\n";
- print " <programlisting>\n";
- print "enum " . $args{'enum'} . " {\n";
- $count = 0;
- foreach $parameter (@{$args{'parameterlist'}}) {
- print " $parameter";
- if ($count != $#{$args{'parameterlist'}}) {
- $count++;
- print ",";
- }
- print "\n";
- }
- print "};";
- print " </programlisting>\n";
- print "</refsynopsisdiv>\n";
-
- print "<refsect1>\n";
- print " <title>Constants</title>\n";
- print " <variablelist>\n";
- foreach $parameter (@{$args{'parameterlist'}}) {
- my $parameter_name = $parameter;
- $parameter_name =~ s/\[.*//;
-
- print " <varlistentry>";
- print " <term>$parameter</term>\n";
- print " <listitem><para>\n";
- output_highlight($args{'parameterdescs'}{$parameter_name});
- print " </para></listitem>\n";
- print " </varlistentry>\n";
- }
- print " </variablelist>\n";
- print "</refsect1>\n";
-
- output_section_xml(@_);
-
- print "</refentry>\n\n";
-}
-
-# output typedef in XML DocBook
-sub output_typedef_xml(%) {
- my %args = %{$_[0]};
- my ($parameter, $section);
- my $id;
-
- $id = "API-typedef-" . $args{'typedef'};
- $id =~ s/[^A-Za-z0-9]/-/g;
-
- print "<refentry id=\"$id\">\n";
- print "<refentryinfo>\n";
- print " <title>LINUX</title>\n";
- print " <productname>Kernel Hackers Manual</productname>\n";
- print " <date>$man_date</date>\n";
- print "</refentryinfo>\n";
- print "<refmeta>\n";
- print " <refentrytitle><phrase>typedef " . $args{'typedef'} . "</phrase></refentrytitle>\n";
- print " <manvolnum>9</manvolnum>\n";
- print "</refmeta>\n";
- print "<refnamediv>\n";
- print " <refname>typedef " . $args{'typedef'} . "</refname>\n";
- print " <refpurpose>\n";
- print " ";
- output_highlight ($args{'purpose'});
- print " </refpurpose>\n";
- print "</refnamediv>\n";
-
- print "<refsynopsisdiv>\n";
- print " <title>Synopsis</title>\n";
- print " <synopsis>typedef " . $args{'typedef'} . ";</synopsis>\n";
- print "</refsynopsisdiv>\n";
-
- output_section_xml(@_);
-
- print "</refentry>\n\n";
-}
-
-# output in XML DocBook
-sub output_blockhead_xml(%) {
- my %args = %{$_[0]};
- my ($parameter, $section);
- my $count;
-
- my $id = $args{'module'};
- $id =~ s/[^A-Za-z0-9]/-/g;
-
- # print out each section
- $lineprefix=" ";
- foreach $section (@{$args{'sectionlist'}}) {
- if (!$args{'content-only'}) {
- print "<refsect1>\n <title>$section</title>\n";
- }
- if ($section =~ m/EXAMPLE/i) {
- print "<example><para>\n";
- $output_preformatted = 1;
- } else {
- print "<para>\n";
- }
- output_highlight($args{'sections'}{$section});
- $output_preformatted = 0;
- if ($section =~ m/EXAMPLE/i) {
- print "</para></example>\n";
- } else {
- print "</para>";
- }
- if (!$args{'content-only'}) {
- print "\n</refsect1>\n";
- }
- }
-
- print "\n\n";
-}
-
-# output in XML DocBook
-sub output_function_gnome {
- my %args = %{$_[0]};
- my ($parameter, $section);
- my $count;
- my $id;
-
- $id = $args{'module'} . "-" . $args{'function'};
- $id =~ s/[^A-Za-z0-9]/-/g;
-
- print "<sect2>\n";
- print " <title id=\"$id\">" . $args{'function'} . "</title>\n";
-
- print " <funcsynopsis>\n";
- print " <funcdef>" . $args{'functiontype'} . " ";
- print "<function>" . $args{'function'} . " ";
- print "</function></funcdef>\n";
-
- $count = 0;
- if ($#{$args{'parameterlist'}} >= 0) {
- foreach $parameter (@{$args{'parameterlist'}}) {
- $type = $args{'parametertypes'}{$parameter};
- if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
- # pointer-to-function
- print " <paramdef>$1 <parameter>$parameter</parameter>)\n";
- print " <funcparams>$2</funcparams></paramdef>\n";
- } else {
- print " <paramdef>" . $type;
- print " <parameter>$parameter</parameter></paramdef>\n";
- }
- }
- } else {
- print " <void>\n";
- }
- print " </funcsynopsis>\n";
- if ($#{$args{'parameterlist'}} >= 0) {
- print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";
- print "<tgroup cols=\"2\">\n";
- print "<colspec colwidth=\"2*\">\n";
- print "<colspec colwidth=\"8*\">\n";
- print "<tbody>\n";
- foreach $parameter (@{$args{'parameterlist'}}) {
- my $parameter_name = $parameter;
- $parameter_name =~ s/\[.*//;
-
- print " <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
- print " <entry>\n";
- $lineprefix=" ";
- output_highlight($args{'parameterdescs'}{$parameter_name});
- print " </entry></row>\n";
- }
- print " </tbody></tgroup></informaltable>\n";
- } else {
- print " <para>\n None\n </para>\n";
- }
-
- # print out each section
- $lineprefix=" ";
- foreach $section (@{$args{'sectionlist'}}) {
- print "<simplesect>\n <title>$section</title>\n";
- if ($section =~ m/EXAMPLE/i) {
- print "<example><programlisting>\n";
- $output_preformatted = 1;
- } else {
- }
- print "<para>\n";
- output_highlight($args{'sections'}{$section});
- $output_preformatted = 0;
- print "</para>\n";
- if ($section =~ m/EXAMPLE/i) {
- print "</programlisting></example>\n";
- } else {
- }
- print " </simplesect>\n";
- }
-
- print "</sect2>\n\n";
-}
-
##
# output function in man
sub output_function_man(%) {
@@ -1694,161 +740,6 @@ sub output_blockhead_man(%) {
}
}
-##
-# output in text
-sub output_function_text(%) {
- my %args = %{$_[0]};
- my ($parameter, $section);
- my $start;
-
- print "Name:\n\n";
- print $args{'function'} . " - " . $args{'purpose'} . "\n";
-
- print "\nSynopsis:\n\n";
- if ($args{'functiontype'} ne "") {
- $start = $args{'functiontype'} . " " . $args{'function'} . " (";
- } else {
- $start = $args{'function'} . " (";
- }
- print $start;
-
- my $count = 0;
- foreach my $parameter (@{$args{'parameterlist'}}) {
- $type = $args{'parametertypes'}{$parameter};
- if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
- # pointer-to-function
- print $1 . $parameter . ") (" . $2;
- } else {
- print $type . " " . $parameter;
- }
- if ($count != $#{$args{'parameterlist'}}) {
- $count++;
- print ",\n";
- print " " x length($start);
- } else {
- print ");\n\n";
- }
- }
-
- print "Arguments:\n\n";
- foreach $parameter (@{$args{'parameterlist'}}) {
- my $parameter_name = $parameter;
- $parameter_name =~ s/\[.*//;
-
- print $parameter . "\n\t" . $args{'parameterdescs'}{$parameter_name} . "\n";
- }
- output_section_text(@_);
-}
-
-#output sections in text
-sub output_section_text(%) {
- my %args = %{$_[0]};
- my $section;
-
- print "\n";
- foreach $section (@{$args{'sectionlist'}}) {
- print "$section:\n\n";
- output_highlight($args{'sections'}{$section});
- }
- print "\n\n";
-}
-
-# output enum in text
-sub output_enum_text(%) {
- my %args = %{$_[0]};
- my ($parameter);
- my $count;
- print "Enum:\n\n";
-
- print "enum " . $args{'enum'} . " - " . $args{'purpose'} . "\n\n";
- print "enum " . $args{'enum'} . " {\n";
- $count = 0;
- foreach $parameter (@{$args{'parameterlist'}}) {
- print "\t$parameter";
- if ($count != $#{$args{'parameterlist'}}) {
- $count++;
- print ",";
- }
- print "\n";
- }
- print "};\n\n";
-
- print "Constants:\n\n";
- foreach $parameter (@{$args{'parameterlist'}}) {
- print "$parameter\n\t";
- print $args{'parameterdescs'}{$parameter} . "\n";
- }
-
- output_section_text(@_);
-}
-
-# output typedef in text
-sub output_typedef_text(%) {
- my %args = %{$_[0]};
- my ($parameter);
- my $count;
- print "Typedef:\n\n";
-
- print "typedef " . $args{'typedef'} . " - " . $args{'purpose'} . "\n";
- output_section_text(@_);
-}
-
-# output struct as text
-sub output_struct_text(%) {
- my %args = %{$_[0]};
- my ($parameter);
-
- print $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "\n\n";
- print $args{'type'} . " " . $args{'struct'} . " {\n";
- foreach $parameter (@{$args{'parameterlist'}}) {
- if ($parameter =~ /^#/) {
- print "$parameter\n";
- next;
- }
-
- my $parameter_name = $parameter;
- $parameter_name =~ s/\[.*//;
-
- ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
- $type = $args{'parametertypes'}{$parameter};
- if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
- # pointer-to-function
- print "\t$1 $parameter) ($2);\n";
- } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
- # bitfield
- print "\t$1 $parameter$2;\n";
- } else {
- print "\t" . $type . " " . $parameter . ";\n";
- }
- }
- print "};\n\n";
-
- print "Members:\n\n";
- foreach $parameter (@{$args{'parameterlist'}}) {
- ($parameter =~ /^#/) && next;
-
- my $parameter_name = $parameter;
- $parameter_name =~ s/\[.*//;
-
- ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
- print "$parameter\n\t";
- print $args{'parameterdescs'}{$parameter_name} . "\n";
- }
- print "\n";
- output_section_text(@_);
-}
-
-sub output_blockhead_text(%) {
- my %args = %{$_[0]};
- my ($parameter, $section);
-
- foreach $section (@{$args{'sectionlist'}}) {
- print " $section:\n";
- print " -> ";
- output_highlight($args{'sections'}{$section});
- }
-}
-
##
# output in restructured text
#
@@ -2083,44 +974,6 @@ sub output_struct_rst(%) {
output_section_rst(@_);
}
-
-## list mode output functions
-
-sub output_function_list(%) {
- my %args = %{$_[0]};
-
- print $args{'function'} . "\n";
-}
-
-# output enum in list
-sub output_enum_list(%) {
- my %args = %{$_[0]};
- print $args{'enum'} . "\n";
-}
-
-# output typedef in list
-sub output_typedef_list(%) {
- my %args = %{$_[0]};
- print $args{'typedef'} . "\n";
-}
-
-# output struct as list
-sub output_struct_list(%) {
- my %args = %{$_[0]};
-
- print $args{'struct'} . "\n";
-}
-
-sub output_blockhead_list(%) {
- my %args = %{$_[0]};
- my ($parameter, $section);
-
- foreach $section (@{$args{'sectionlist'}}) {
- print "DOC: $section\n";
- }
-}
-
-
## none mode output functions
sub output_function_none(%) {
@@ -2827,7 +1680,7 @@ sub process_proto_type($$) {
# just before actual output; (this is done by local_unescape())
sub xml_escape($) {
my $text = shift;
- if (($output_mode eq "text") || ($output_mode eq "man")) {
+ if ($output_mode eq "man") {
return $text;
}
$text =~ s/\&/\\\\\\amp;/g;
@@ -2839,7 +1692,7 @@ sub xml_escape($) {
# xml_unescape: reverse the effects of xml_escape
sub xml_unescape($) {
my $text = shift;
- if (($output_mode eq "text") || ($output_mode eq "man")) {
+ if ($output_mode eq "man") {
return $text;
}
$text =~ s/\\\\\\amp;/\&/g;
@@ -2852,7 +1705,7 @@ sub xml_unescape($) {
# local escape strings look like: '\\\\menmonic:' (that's 4 backslashes)
sub local_unescape($) {
my $text = shift;
- if (($output_mode eq "text") || ($output_mode eq "man")) {
+ if ($output_mode eq "man") {
return $text;
}
$text =~ s/\\\\\\\\lt:/</g;
@@ -3174,34 +2027,6 @@ sub process_file($) {
if (($output_selection == OUTPUT_INCLUDE) && ($show_not_found == 1)) {
print STDERR " Was looking for '$_'.\n" for keys %function_table;
}
- if ($output_mode eq "xml") {
- # The template wants at least one RefEntry here; make one.
- print "<refentry>\n";
- print " <refnamediv>\n";
- print " <refname>\n";
- print " ${orig_file}\n";
- print " </refname>\n";
- print " <refpurpose>\n";
- print " Document generation inconsistency\n";
- print " </refpurpose>\n";
- print " </refnamediv>\n";
- print " <refsect1>\n";
- print " <title>\n";
- print " Oops\n";
- print " </title>\n";
- print " <warning>\n";
- print " <para>\n";
- print " The template for this document tried to insert\n";
- print " the structured comment from the file\n";
- print " <filename>${orig_file}</filename> at this point,\n";
- print " but none was found.\n";
- print " This dummy section is inserted to allow\n";
- print " generation to continue.\n";
- print " </para>\n";
- print " </warning>\n";
- print " </refsect1>\n";
- print "</refentry>\n";
- }
}
}
--
2.14.3
^ permalink raw reply related [flat|nested] 28+ messages in thread* [PATCH v4 09/18] scripts: kernel-doc: improve argument handling
2017-12-18 12:30 [PATCH v4 00/18] kernel-doc: add supported to document nested structs Mauro Carvalho Chehab
` (7 preceding siblings ...)
2017-12-18 12:30 ` [PATCH v4 08/18] scripts: kernel-doc: get rid of unused output formats Mauro Carvalho Chehab
@ 2017-12-18 12:30 ` Mauro Carvalho Chehab
2017-12-18 12:30 ` [PATCH v4 10/18] scripts: kernel-doc: change default to ReST format Mauro Carvalho Chehab
` (9 subsequent siblings)
18 siblings, 0 replies; 28+ messages in thread
From: Mauro Carvalho Chehab @ 2017-12-18 12:30 UTC (permalink / raw)
To: Linux Media Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Linux Doc Mailing List
Right now, if one uses "--rst" instead of "-rst", it just
ignore the argument and produces a man page. Change the
logic to accept both "-cmd" and "--cmd". Also, if
"cmd" doesn't exist, print the usage information and exit.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
scripts/kernel-doc | 36 ++++++++++++++++++++----------------
1 file changed, 20 insertions(+), 16 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index c8ad05eb3e5e..11aec7469776 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -391,47 +391,51 @@ my $undescribed = "-- undescribed --";
reset_state();
-while ($ARGV[0] =~ m/^-(.*)/) {
- my $cmd = shift @ARGV;
- if ($cmd eq "-man") {
+while ($ARGV[0] =~ m/^--?(.*)/) {
+ my $cmd = $1;
+ shift @ARGV;
+ if ($cmd eq "man") {
$output_mode = "man";
@highlights = @highlights_man;
$blankline = $blankline_man;
- } elsif ($cmd eq "-rst") {
+ } elsif ($cmd eq "rst") {
$output_mode = "rst";
@highlights = @highlights_rst;
$blankline = $blankline_rst;
- } elsif ($cmd eq "-none") {
+ } elsif ($cmd eq "none") {
$output_mode = "none";
- } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
+ } elsif ($cmd eq "module") { # not needed for XML, inherits from calling document
$modulename = shift @ARGV;
- } elsif ($cmd eq "-function") { # to only output specific functions
+ } elsif ($cmd eq "function") { # to only output specific functions
$output_selection = OUTPUT_INCLUDE;
$function = shift @ARGV;
$function_table{$function} = 1;
- } elsif ($cmd eq "-nofunction") { # output all except specific functions
+ } elsif ($cmd eq "nofunction") { # output all except specific functions
$output_selection = OUTPUT_EXCLUDE;
$function = shift @ARGV;
$function_table{$function} = 1;
- } elsif ($cmd eq "-export") { # only exported symbols
+ } elsif ($cmd eq "export") { # only exported symbols
$output_selection = OUTPUT_EXPORTED;
%function_table = ();
- } elsif ($cmd eq "-internal") { # only non-exported symbols
+ } elsif ($cmd eq "internal") { # only non-exported symbols
$output_selection = OUTPUT_INTERNAL;
%function_table = ();
- } elsif ($cmd eq "-export-file") {
+ } elsif ($cmd eq "export-file") {
my $file = shift @ARGV;
push(@export_file_list, $file);
- } elsif ($cmd eq "-v") {
+ } elsif ($cmd eq "v") {
$verbose = 1;
- } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
+ } elsif (($cmd eq "h") || ($cmd eq "help")) {
usage();
- } elsif ($cmd eq '-no-doc-sections') {
+ } elsif ($cmd eq 'no-doc-sections') {
$no_doc_sections = 1;
- } elsif ($cmd eq '-enable-lineno') {
+ } elsif ($cmd eq 'enable-lineno') {
$enable_lineno = 1;
- } elsif ($cmd eq '-show-not-found') {
+ } elsif ($cmd eq 'show-not-found') {
$show_not_found = 1;
+ } else {
+ # Unknown argument
+ usage();
}
}
--
2.14.3
^ permalink raw reply related [flat|nested] 28+ messages in thread* [PATCH v4 10/18] scripts: kernel-doc: change default to ReST format
2017-12-18 12:30 [PATCH v4 00/18] kernel-doc: add supported to document nested structs Mauro Carvalho Chehab
` (8 preceding siblings ...)
2017-12-18 12:30 ` [PATCH v4 09/18] scripts: kernel-doc: improve argument handling Mauro Carvalho Chehab
@ 2017-12-18 12:30 ` Mauro Carvalho Chehab
2017-12-18 12:30 ` [PATCH v4 11/18] scripts: kernel-doc: replace tabs by spaces Mauro Carvalho Chehab
` (8 subsequent siblings)
18 siblings, 0 replies; 28+ messages in thread
From: Mauro Carvalho Chehab @ 2017-12-18 12:30 UTC (permalink / raw)
To: Linux Media Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Linux Doc Mailing List
Right now, if kernel-doc is called without arguments, it
defaults to man pages. IMO, it makes more sense to
default to ReST, as this is the output that it is most
used nowadays, and it easier to check if everything got
parsed fine on an enriched text mode format.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
scripts/kernel-doc | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 11aec7469776..e417d93575b9 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -268,12 +268,12 @@ my $kernelversion;
my $dohighlight = "";
my $verbose = 0;
-my $output_mode = "man";
+my $output_mode = "rst";
my $output_preformatted = 0;
my $no_doc_sections = 0;
my $enable_lineno = 0;
-my @highlights = @highlights_man;
-my $blankline = $blankline_man;
+my @highlights = @highlights_rst;
+my $blankline = $blankline_rst;
my $modulename = "Kernel API";
use constant {
--
2.14.3
^ permalink raw reply related [flat|nested] 28+ messages in thread* [PATCH v4 11/18] scripts: kernel-doc: replace tabs by spaces
2017-12-18 12:30 [PATCH v4 00/18] kernel-doc: add supported to document nested structs Mauro Carvalho Chehab
` (9 preceding siblings ...)
2017-12-18 12:30 ` [PATCH v4 10/18] scripts: kernel-doc: change default to ReST format Mauro Carvalho Chehab
@ 2017-12-18 12:30 ` Mauro Carvalho Chehab
2017-12-18 12:30 ` [PATCH v4 12/18] scripts: kernel-doc: parse next structs/unions Mauro Carvalho Chehab
` (7 subsequent siblings)
18 siblings, 0 replies; 28+ messages in thread
From: Mauro Carvalho Chehab @ 2017-12-18 12:30 UTC (permalink / raw)
To: Linux Media Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Linux Doc Mailing List
Sphinx has a hard time dealing with tabs, causing it to
misinterpret paragraph continuation.
As we're now mainly focused on supporting ReST output,
replace tabs by spaces, in order to avoid troubles when
the output is parsed by Sphinx.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
scripts/kernel-doc | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index e417d93575b9..05aadac0612a 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1579,7 +1579,7 @@ sub tracepoint_munge($) {
sub syscall_munge() {
my $void = 0;
- $prototype =~ s@[\r\n\t]+@ @gos; # strip newlines/CR's/tabs
+ $prototype =~ s@[\r\n]+@ @gos; # strip newlines/CR's
## if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
if ($prototype =~ m/SYSCALL_DEFINE0/) {
$void = 1;
@@ -1778,6 +1778,8 @@ sub process_file($) {
while (s/\\\s*$//) {
$_ .= <IN>;
}
+ # Replace tabs by spaces
+ while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
if ($state == STATE_NORMAL) {
if (/$doc_start/o) {
$state = STATE_NAME; # next line is always the function name
@@ -1877,8 +1879,7 @@ sub process_file($) {
$in_purpose = 0;
$contents = $newcontents;
$new_start_line = $.;
- while ((substr($contents, 0, 1) eq " ") ||
- substr($contents, 0, 1) eq "\t") {
+ while (substr($contents, 0, 1) eq " ") {
$contents = substr($contents, 1);
}
if ($contents ne "") {
@@ -1947,8 +1948,7 @@ sub process_file($) {
$contents = $2;
$new_start_line = $.;
if ($contents ne "") {
- while ((substr($contents, 0, 1) eq " ") ||
- substr($contents, 0, 1) eq "\t") {
+ while (substr($contents, 0, 1) eq " ") {
$contents = substr($contents, 1);
}
$contents .= "\n";
--
2.14.3
^ permalink raw reply related [flat|nested] 28+ messages in thread* [PATCH v4 12/18] scripts: kernel-doc: parse next structs/unions
2017-12-18 12:30 [PATCH v4 00/18] kernel-doc: add supported to document nested structs Mauro Carvalho Chehab
` (10 preceding siblings ...)
2017-12-18 12:30 ` [PATCH v4 11/18] scripts: kernel-doc: replace tabs by spaces Mauro Carvalho Chehab
@ 2017-12-18 12:30 ` Mauro Carvalho Chehab
2017-12-18 12:30 ` [PATCH v4 13/18] scripts: kernel-doc: get rid of $nested parameter Mauro Carvalho Chehab
` (6 subsequent siblings)
18 siblings, 0 replies; 28+ messages in thread
From: Mauro Carvalho Chehab @ 2017-12-18 12:30 UTC (permalink / raw)
To: Linux Media Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab,
Linux Doc Mailing List, Tom Saeger
There are several places within the Kernel tree with nested
structs/unions, like this one:
struct ingenic_cgu_clk_info {
const char *name;
enum {
CGU_CLK_NONE = 0,
CGU_CLK_EXT = BIT(0),
CGU_CLK_PLL = BIT(1),
CGU_CLK_GATE = BIT(2),
CGU_CLK_MUX = BIT(3),
CGU_CLK_MUX_GLITCHFREE = BIT(4),
CGU_CLK_DIV = BIT(5),
CGU_CLK_FIXDIV = BIT(6),
CGU_CLK_CUSTOM = BIT(7),
} type;
int parents[4];
union {
struct ingenic_cgu_pll_info pll;
struct {
struct ingenic_cgu_gate_info gate;
struct ingenic_cgu_mux_info mux;
struct ingenic_cgu_div_info div;
struct ingenic_cgu_fixdiv_info fixdiv;
};
struct ingenic_cgu_custom_info custom;
};
};
Currently, such struct is documented as:
**Definition**
::
struct ingenic_cgu_clk_info {
const char * name;
};
**Members**
``name``
name of the clock
With is obvioulsy wrong. It also generates an error:
drivers/clk/ingenic/cgu.h:169: warning: No description found for parameter 'enum'
However, there's nothing wrong with this kernel-doc markup: everything
is documented there.
It makes sense to document all fields there. So, add a
way for the core to parse those structs.
With this patch, all documented fields will properly generate
documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/doc-guide/kernel-doc.rst | 46 +++++++++++++
scripts/kernel-doc | 121 ++++++++++++++++++---------------
2 files changed, 114 insertions(+), 53 deletions(-)
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index 14c226e8154f..722d4525f7cf 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -281,6 +281,52 @@ comment block.
The kernel-doc data structure comments describe each member of the structure,
in order, with the member descriptions.
+Nested structs/unions
+~~~~~~~~~~~~~~~~~~~~~
+
+It is possible to document nested structs unions, like::
+
+ /**
+ * struct nested_foobar - a struct with nested unions and structs
+ * @arg1: - first argument of anonymous union/anonymous struct
+ * @arg2: - second argument of anonymous union/anonymous struct
+ * @arg3: - third argument of anonymous union/anonymous struct
+ * @arg4: - fourth argument of anonymous union/anonymous struct
+ * @bar.st1.arg1 - first argument of struct st1 on union bar
+ * @bar.st1.arg2 - second argument of struct st1 on union bar
+ * @bar.st2.arg1 - first argument of struct st2 on union bar
+ * @bar.st2.arg2 - second argument of struct st2 on union bar
+ struct nested_foobar {
+ /* Anonymous union/struct*/
+ union {
+ struct {
+ int arg1;
+ int arg2;
+ }
+ struct {
+ void *arg3;
+ int arg4;
+ }
+ }
+ union {
+ struct {
+ int arg1;
+ int arg2;
+ } st1;
+ struct {
+ void *arg1;
+ int arg2;
+ } st2;
+ } bar;
+ };
+
+.. note::
+
+ #) When documenting nested structs or unions, if the struct/union ``foo``
+ is named, the argument ``bar`` inside it should be documented as
+ ``@foo.bar:``
+ #) When the nested struct/union is anonymous, the argument ``bar`` on it
+ should be documented as ``@bar:``
Typedef documentation
---------------------
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 05aadac0612a..b0eb1cd6afbe 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -211,7 +211,7 @@ my $anon_struct_union = 0;
my $type_constant = '\b``([^\`]+)``\b';
my $type_constant2 = '\%([-_\w]+)';
my $type_func = '(\w+)\(\)';
-my $type_param = '\@(\w+(\.\.\.)?)';
+my $type_param = '\@(\w*(\.\w+)*(\.\.\.)?)';
my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params
my $type_env = '(\$\w+)';
my $type_enum = '\&(enum\s*([_\w]+))';
@@ -670,32 +670,12 @@ sub output_struct_man(%) {
print ".SH NAME\n";
print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
+ my $declaration = $args{'definition'};
+ $declaration =~ s/\t/ /g;
+ $declaration =~ s/\n/"\n.br\n.BI \"/g;
print ".SH SYNOPSIS\n";
print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";
-
- foreach my $parameter (@{$args{'parameterlist'}}) {
- if ($parameter =~ /^#/) {
- print ".BI \"$parameter\"\n.br\n";
- next;
- }
- my $parameter_name = $parameter;
- $parameter_name =~ s/\[.*//;
-
- ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
- $type = $args{'parametertypes'}{$parameter};
- if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
- # pointer-to-function
- print ".BI \" " . $1 . "\" " . $parameter . " \") (" . $2 . ")" . "\"\n;\n";
- } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
- # bitfield
- print ".BI \" " . $1 . "\ \" " . $parameter . $2 . " \"" . "\"\n;\n";
- } else {
- $type =~ s/([^\*])$/$1 /;
- print ".BI \" " . $type . "\" " . $parameter . " \"" . "\"\n;\n";
- }
- print "\n.br\n";
- }
- print "};\n.br\n";
+ print ".BI \"$declaration\n};\n.br\n\n";
print ".SH Members\n";
foreach $parameter (@{$args{'parameterlist'}}) {
@@ -933,29 +913,9 @@ sub output_struct_rst(%) {
print "**Definition**\n\n";
print "::\n\n";
- print " " . $args{'type'} . " " . $args{'struct'} . " {\n";
- foreach $parameter (@{$args{'parameterlist'}}) {
- if ($parameter =~ /^#/) {
- print " " . "$parameter\n";
- next;
- }
-
- my $parameter_name = $parameter;
- $parameter_name =~ s/\[.*//;
-
- ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
- $type = $args{'parametertypes'}{$parameter};
- if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
- # pointer-to-function
- print " $1 $parameter) ($2);\n";
- } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
- # bitfield
- print " $1 $parameter$2;\n";
- } else {
- print " " . $type . " " . $parameter . ";\n";
- }
- }
- print " };\n\n";
+ my $declaration = $args{'definition'};
+ $declaration =~ s/\t/ /g;
+ print " " . $args{'type'} . " " . $args{'struct'} . " {\n$declaration };\n\n";
print "**Members**\n\n";
$lineprefix = " ";
@@ -1050,16 +1010,11 @@ sub dump_struct($$) {
$declaration_name = $2;
my $members = $3;
- # ignore embedded structs or unions
- $members =~ s/({.*})//g;
- $nested = $1;
-
# ignore members marked private:
$members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
$members =~ s/\/\*\s*private:.*//gosi;
# strip comments:
$members =~ s/\/\*.*?\*\///gos;
- $nested =~ s/\/\*.*?\*\///gos;
# strip attributes
$members =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
$members =~ s/__aligned\s*\([^;]*\)//gos;
@@ -1073,13 +1028,73 @@ sub dump_struct($$) {
# replace DECLARE_KFIFO_PTR
$members =~ s/DECLARE_KFIFO_PTR\s*\(([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos;
+ my $declaration = $members;
+
+ # Split nested struct/union elements as newer ones
+ my $cont = 1;
+ while ($cont) {
+ $cont = 0;
+ while ($members =~ m/(struct|union)([^{};]+){([^{}]*)}([^{}\;]*)\;/) {
+ my $newmember = "$1 $4;";
+ my $id = $4;
+ my $content = $3;
+ $id =~ s/[:\[].*//;
+ $id =~ s/^\*+//;
+ foreach my $arg (split /;/, $content) {
+ next if ($arg =~ m/^\s*$/);
+ my $type = $arg;
+ my $name = $arg;
+ $type =~ s/\s\S+$//;
+ $name =~ s/.*\s//;
+ $name =~ s/[:\[].*//;
+ $name =~ s/^\*+//;
+ next if (($name =~ m/^\s*$/));
+ if ($id =~ m/^\s*$/) {
+ # anonymous struct/union
+ $newmember .= "$type $name;";
+ } else {
+ $newmember .= "$type $id.$name;";
+ }
+ }
+ $members =~ s/(struct|union)([^{};]+){([^{}]*)}([^{}\;]*)\;/$newmember/;
+ $cont = 1;
+ };
+ };
+
+ # Ignore other nested elements, like enums
+ $members =~ s/({[^\{\}]*})//g;
+ $nested = $decl_type;
+ $nested =~ s/\/\*.*?\*\///gos;
+
create_parameterlist($members, ';', $file);
check_sections($file, $declaration_name, $decl_type, $sectcheck, $struct_actual, $nested);
+ # Adjust declaration for better display
+ $declaration =~ s/([{;])/$1\n/g;
+ $declaration =~ s/}\s+;/};/g;
+ # Better handle inlined enums
+ do {} while ($declaration =~ s/(enum\s+{[^}]+),([^\n])/$1,\n$2/);
+
+ my @def_args = split /\n/, $declaration;
+ my $level = 1;
+ $declaration = "";
+ foreach my $clause (@def_args) {
+ $clause =~ s/^\s+//;
+ $clause =~ s/\s+$//;
+ $clause =~ s/\s+/ /;
+ next if (!$clause);
+ $level-- if ($clause =~ m/(})/ && $level > 1);
+ if (!($clause =~ m/^\s*#/)) {
+ $declaration .= "\t" x $level;
+ }
+ $declaration .= "\t" . $clause . "\n";
+ $level++ if ($clause =~ m/({)/ && !($clause =~m/}/));
+ }
output_declaration($declaration_name,
'struct',
{'struct' => $declaration_name,
'module' => $modulename,
+ 'definition' => $declaration,
'parameterlist' => \@parameterlist,
'parameterdescs' => \%parameterdescs,
'parametertypes' => \%parametertypes,
--
2.14.3
^ permalink raw reply related [flat|nested] 28+ messages in thread* [PATCH v4 13/18] scripts: kernel-doc: get rid of $nested parameter
2017-12-18 12:30 [PATCH v4 00/18] kernel-doc: add supported to document nested structs Mauro Carvalho Chehab
` (11 preceding siblings ...)
2017-12-18 12:30 ` [PATCH v4 12/18] scripts: kernel-doc: parse next structs/unions Mauro Carvalho Chehab
@ 2017-12-18 12:30 ` Mauro Carvalho Chehab
2017-12-18 12:30 ` [PATCH v4 14/18] scripts: kernel-doc: print the declaration name on warnings Mauro Carvalho Chehab
` (5 subsequent siblings)
18 siblings, 0 replies; 28+ messages in thread
From: Mauro Carvalho Chehab @ 2017-12-18 12:30 UTC (permalink / raw)
To: Linux Media Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Linux Doc Mailing List
The check_sections() function has a $nested parameter, meant
to identify when a nested struct is present. As we now have
a logic that handles it, get rid of such parameter.
Suggested-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
scripts/kernel-doc | 19 ++++---------------
1 file changed, 4 insertions(+), 15 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index b0eb1cd6afbe..fadb832733d9 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1003,7 +1003,6 @@ sub dump_union($$) {
sub dump_struct($$) {
my $x = shift;
my $file = shift;
- my $nested;
if ($x =~ /(struct|union)\s+(\w+)\s*{(.*)}/) {
my $decl_type = $1;
@@ -1063,11 +1062,9 @@ sub dump_struct($$) {
# Ignore other nested elements, like enums
$members =~ s/({[^\{\}]*})//g;
- $nested = $decl_type;
- $nested =~ s/\/\*.*?\*\///gos;
create_parameterlist($members, ';', $file);
- check_sections($file, $declaration_name, $decl_type, $sectcheck, $struct_actual, $nested);
+ check_sections($file, $declaration_name, $decl_type, $sectcheck, $struct_actual);
# Adjust declaration for better display
$declaration =~ s/([{;])/$1\n/g;
@@ -1372,8 +1369,8 @@ sub push_parameter($$$) {
$parametertypes{$param} = $type;
}
-sub check_sections($$$$$$) {
- my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck, $nested) = @_;
+sub check_sections($$$$$) {
+ my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck) = @_;
my @sects = split ' ', $sectcheck;
my @prms = split ' ', $prmscheck;
my $err;
@@ -1407,14 +1404,6 @@ sub check_sections($$$$$$) {
"'$sects[$sx]' " .
"description in '$decl_name'\n";
++$warnings;
- } else {
- if ($nested !~ m/\Q$sects[$sx]\E/) {
- print STDERR "${file}:$.: warning: " .
- "Excess $decl_type member " .
- "'$sects[$sx]' " .
- "description in '$decl_name'\n";
- ++$warnings;
- }
}
}
}
@@ -1525,7 +1514,7 @@ sub dump_function($$) {
}
my $prms = join " ", @parameterlist;
- check_sections($file, $declaration_name, "function", $sectcheck, $prms, "");
+ check_sections($file, $declaration_name, "function", $sectcheck, $prms);
# This check emits a lot of warnings at the moment, because many
# functions don't have a 'Return' doc section. So until the number
--
2.14.3
^ permalink raw reply related [flat|nested] 28+ messages in thread* [PATCH v4 14/18] scripts: kernel-doc: print the declaration name on warnings
2017-12-18 12:30 [PATCH v4 00/18] kernel-doc: add supported to document nested structs Mauro Carvalho Chehab
` (12 preceding siblings ...)
2017-12-18 12:30 ` [PATCH v4 13/18] scripts: kernel-doc: get rid of $nested parameter Mauro Carvalho Chehab
@ 2017-12-18 12:30 ` Mauro Carvalho Chehab
2017-12-21 3:40 ` kbuild test robot
2017-12-18 12:30 ` [PATCH v4 15/18] scripts: kernel-doc: handle nested struct function arguments Mauro Carvalho Chehab
` (4 subsequent siblings)
18 siblings, 1 reply; 28+ messages in thread
From: Mauro Carvalho Chehab @ 2017-12-18 12:30 UTC (permalink / raw)
To: Linux Media Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Linux Doc Mailing List
The logic at create_parameterlist()'s ancillary push_parameter()
function has already a way to output the declaration name, with
would help to discover what declaration is missing.
However, currently, the logic is utterly broken, as it uses
the var $type with a wrong meaning. With the current code,
it will never print anything. I suspect that originally
it was using the second argument of output_declaration().
I opted to not rely on a globally defined $declaration_name,
but, instead, to pass it explicitly as a parameter.
While here, I removed a unaligned check for !$anon_struct_union.
This is not needed, as, if $anon_struct_union is not zero,
$parameterdescs{$param} will be defined.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
scripts/kernel-doc | 38 ++++++++++++++++----------------------
1 file changed, 16 insertions(+), 22 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index fadb832733d9..c97b89f47795 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1063,7 +1063,7 @@ sub dump_struct($$) {
# Ignore other nested elements, like enums
$members =~ s/({[^\{\}]*})//g;
- create_parameterlist($members, ';', $file);
+ create_parameterlist($members, ';', $file, $declaration_name);
check_sections($file, $declaration_name, $decl_type, $sectcheck, $struct_actual);
# Adjust declaration for better display
@@ -1172,7 +1172,7 @@ sub dump_typedef($$) {
$declaration_name = $2;
my $args = $3;
- create_parameterlist($args, ',', $file);
+ create_parameterlist($args, ',', $file, $declaration_name);
output_declaration($declaration_name,
'function',
@@ -1221,10 +1221,11 @@ sub save_struct_actual($) {
$struct_actual = $struct_actual . $actual . " ";
}
-sub create_parameterlist($$$) {
+sub create_parameterlist($$$$) {
my $args = shift;
my $splitter = shift;
my $file = shift;
+ my $declaration_name = shift;
my $type;
my $param;
@@ -1254,7 +1255,7 @@ sub create_parameterlist($$$) {
$type = $arg;
$type =~ s/([^\(]+\(\*?)\s*$param/$1/;
save_struct_actual($param);
- push_parameter($param, $type, $file);
+ push_parameter($param, $type, $file, $declaration_name);
} elsif ($arg) {
$arg =~ s/\s*:\s*/:/g;
$arg =~ s/\s*\[/\[/g;
@@ -1279,27 +1280,28 @@ sub create_parameterlist($$$) {
foreach $param (@args) {
if ($param =~ m/^(\*+)\s*(.*)/) {
save_struct_actual($2);
- push_parameter($2, "$type $1", $file);
+ push_parameter($2, "$type $1", $file, $declaration_name);
}
elsif ($param =~ m/(.*?):(\d+)/) {
if ($type ne "") { # skip unnamed bit-fields
save_struct_actual($1);
- push_parameter($1, "$type:$2", $file)
+ push_parameter($1, "$type:$2", $file, $declaration_name)
}
}
else {
save_struct_actual($param);
- push_parameter($param, $type, $file);
+ push_parameter($param, $type, $file, $declaration_name);
}
}
}
}
}
-sub push_parameter($$$) {
+sub push_parameter($$$$) {
my $param = shift;
my $type = shift;
my $file = shift;
+ my $declaration_name = shift;
if (($anon_struct_union == 1) && ($type eq "") &&
($param eq "}")) {
@@ -1336,21 +1338,13 @@ sub push_parameter($$$) {
# warn if parameter has no description
# (but ignore ones starting with # as these are not parameters
# but inline preprocessor statements);
- # also ignore unnamed structs/unions;
- if (!$anon_struct_union) {
+ # Note: It will also ignore void params and unnamed structs/unions
if (!defined $parameterdescs{$param} && $param !~ /^#/) {
+ $parameterdescs{$param} = $undescribed;
- $parameterdescs{$param} = $undescribed;
-
- if (($type eq 'function') || ($type eq 'enum')) {
- print STDERR "${file}:$.: warning: Function parameter ".
- "or member '$param' not " .
- "described in '$declaration_name'\n";
- }
- print STDERR "${file}:$.: warning:" .
- " No description found for parameter '$param'\n";
- ++$warnings;
- }
+ print STDERR
+ "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n";
+ ++$warnings;
}
$param = xml_escape($param);
@@ -1507,7 +1501,7 @@ sub dump_function($$) {
$declaration_name = $2;
my $args = $3;
- create_parameterlist($args, ',', $file);
+ create_parameterlist($args, ',', $file, $declaration_name);
} else {
print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
return;
--
2.14.3
^ permalink raw reply related [flat|nested] 28+ messages in thread* Re: [PATCH v4 14/18] scripts: kernel-doc: print the declaration name on warnings
2017-12-18 12:30 ` [PATCH v4 14/18] scripts: kernel-doc: print the declaration name on warnings Mauro Carvalho Chehab
@ 2017-12-21 3:40 ` kbuild test robot
0 siblings, 0 replies; 28+ messages in thread
From: kbuild test robot @ 2017-12-21 3:40 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: kbuild-all, Linux Media Mailing List, Jonathan Corbet,
Mauro Carvalho Chehab, Mauro Carvalho Chehab,
Linux Doc Mailing List
[-- Attachment #1: Type: text/plain, Size: 35917 bytes --]
Hi Mauro,
I love your patch! Perhaps something to improve:
[auto build test WARNING on lwn/docs-next]
[also build test WARNING on v4.15-rc4 next-20171220]
[cannot apply to linus/master]
[if your patch is applied to the wrong git tree, please drop us a note to help improve the system]
url: https://github.com/0day-ci/linux/commits/Mauro-Carvalho-Chehab/kernel-doc-add-supported-to-document-nested-structs/20171221-055609
base: git://git.lwn.net/linux-2.6 docs-next
reproduce: make htmldocs
All warnings (new ones prefixed by >>):
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
include/crypto/hash.h:89: warning: duplicate section name 'Note'
include/crypto/hash.h:95: warning: duplicate section name 'Note'
include/crypto/hash.h:102: warning: duplicate section name 'Note'
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
include/crypto/hash.h:89: warning: duplicate section name 'Note'
include/crypto/hash.h:95: warning: duplicate section name 'Note'
include/crypto/hash.h:102: warning: duplicate section name 'Note'
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
include/crypto/hash.h:89: warning: duplicate section name 'Note'
include/crypto/hash.h:95: warning: duplicate section name 'Note'
include/crypto/hash.h:102: warning: duplicate section name 'Note'
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
include/crypto/hash.h:89: warning: duplicate section name 'Note'
include/crypto/hash.h:95: warning: duplicate section name 'Note'
include/crypto/hash.h:102: warning: duplicate section name 'Note'
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
include/crypto/hash.h:89: warning: duplicate section name 'Note'
include/crypto/hash.h:95: warning: duplicate section name 'Note'
include/crypto/hash.h:102: warning: duplicate section name 'Note'
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
include/crypto/hash.h:89: warning: duplicate section name 'Note'
include/crypto/hash.h:95: warning: duplicate section name 'Note'
include/crypto/hash.h:102: warning: duplicate section name 'Note'
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
include/crypto/hash.h:89: warning: duplicate section name 'Note'
include/crypto/hash.h:95: warning: duplicate section name 'Note'
include/crypto/hash.h:102: warning: duplicate section name 'Note'
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
include/crypto/hash.h:89: warning: duplicate section name 'Note'
include/crypto/hash.h:95: warning: duplicate section name 'Note'
include/crypto/hash.h:102: warning: duplicate section name 'Note'
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
>> include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.ablkcipher' not described in 'crypto_alg'
>> include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.blkcipher' not described in 'crypto_alg'
>> include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.cipher' not described in 'crypto_alg'
>> include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.compress' not described in 'crypto_alg'
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
>> include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.ablkcipher' not described in 'crypto_alg'
>> include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.blkcipher' not described in 'crypto_alg'
>> include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.cipher' not described in 'crypto_alg'
>> include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.compress' not described in 'crypto_alg'
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
>> include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.ablkcipher' not described in 'crypto_alg'
>> include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.blkcipher' not described in 'crypto_alg'
>> include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.cipher' not described in 'crypto_alg'
>> include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.compress' not described in 'crypto_alg'
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
>> include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.ablkcipher' not described in 'crypto_alg'
>> include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.blkcipher' not described in 'crypto_alg'
>> include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.cipher' not described in 'crypto_alg'
>> include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.compress' not described in 'crypto_alg'
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
>> include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.ablkcipher' not described in 'crypto_alg'
>> include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.blkcipher' not described in 'crypto_alg'
>> include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.cipher' not described in 'crypto_alg'
>> include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.compress' not described in 'crypto_alg'
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1058.
vim +469 include/linux/crypto.h
^1da177e4 Linus Torvalds 2005-04-16 364
0d7f488f0 Stephan Mueller 2014-11-12 365 /**
0d7f488f0 Stephan Mueller 2014-11-12 366 * struct crypto_alg - definition of a cryptograpic cipher algorithm
0d7f488f0 Stephan Mueller 2014-11-12 367 * @cra_flags: Flags describing this transformation. See include/linux/crypto.h
0d7f488f0 Stephan Mueller 2014-11-12 368 * CRYPTO_ALG_* flags for the flags which go in here. Those are
0d7f488f0 Stephan Mueller 2014-11-12 369 * used for fine-tuning the description of the transformation
0d7f488f0 Stephan Mueller 2014-11-12 370 * algorithm.
0d7f488f0 Stephan Mueller 2014-11-12 371 * @cra_blocksize: Minimum block size of this transformation. The size in bytes
0d7f488f0 Stephan Mueller 2014-11-12 372 * of the smallest possible unit which can be transformed with
0d7f488f0 Stephan Mueller 2014-11-12 373 * this algorithm. The users must respect this value.
0d7f488f0 Stephan Mueller 2014-11-12 374 * In case of HASH transformation, it is possible for a smaller
0d7f488f0 Stephan Mueller 2014-11-12 375 * block than @cra_blocksize to be passed to the crypto API for
0d7f488f0 Stephan Mueller 2014-11-12 376 * transformation, in case of any other transformation type, an
0d7f488f0 Stephan Mueller 2014-11-12 377 * error will be returned upon any attempt to transform smaller
0d7f488f0 Stephan Mueller 2014-11-12 378 * than @cra_blocksize chunks.
0d7f488f0 Stephan Mueller 2014-11-12 379 * @cra_ctxsize: Size of the operational context of the transformation. This
0d7f488f0 Stephan Mueller 2014-11-12 380 * value informs the kernel crypto API about the memory size
0d7f488f0 Stephan Mueller 2014-11-12 381 * needed to be allocated for the transformation context.
0d7f488f0 Stephan Mueller 2014-11-12 382 * @cra_alignmask: Alignment mask for the input and output data buffer. The data
0d7f488f0 Stephan Mueller 2014-11-12 383 * buffer containing the input data for the algorithm must be
0d7f488f0 Stephan Mueller 2014-11-12 384 * aligned to this alignment mask. The data buffer for the
0d7f488f0 Stephan Mueller 2014-11-12 385 * output data must be aligned to this alignment mask. Note that
0d7f488f0 Stephan Mueller 2014-11-12 386 * the Crypto API will do the re-alignment in software, but
0d7f488f0 Stephan Mueller 2014-11-12 387 * only under special conditions and there is a performance hit.
0d7f488f0 Stephan Mueller 2014-11-12 388 * The re-alignment happens at these occasions for different
0d7f488f0 Stephan Mueller 2014-11-12 389 * @cra_u types: cipher -- For both input data and output data
0d7f488f0 Stephan Mueller 2014-11-12 390 * buffer; ahash -- For output hash destination buf; shash --
0d7f488f0 Stephan Mueller 2014-11-12 391 * For output hash destination buf.
0d7f488f0 Stephan Mueller 2014-11-12 392 * This is needed on hardware which is flawed by design and
0d7f488f0 Stephan Mueller 2014-11-12 393 * cannot pick data from arbitrary addresses.
0d7f488f0 Stephan Mueller 2014-11-12 394 * @cra_priority: Priority of this transformation implementation. In case
0d7f488f0 Stephan Mueller 2014-11-12 395 * multiple transformations with same @cra_name are available to
0d7f488f0 Stephan Mueller 2014-11-12 396 * the Crypto API, the kernel will use the one with highest
0d7f488f0 Stephan Mueller 2014-11-12 397 * @cra_priority.
0d7f488f0 Stephan Mueller 2014-11-12 398 * @cra_name: Generic name (usable by multiple implementations) of the
0d7f488f0 Stephan Mueller 2014-11-12 399 * transformation algorithm. This is the name of the transformation
0d7f488f0 Stephan Mueller 2014-11-12 400 * itself. This field is used by the kernel when looking up the
0d7f488f0 Stephan Mueller 2014-11-12 401 * providers of particular transformation.
0d7f488f0 Stephan Mueller 2014-11-12 402 * @cra_driver_name: Unique name of the transformation provider. This is the
0d7f488f0 Stephan Mueller 2014-11-12 403 * name of the provider of the transformation. This can be any
0d7f488f0 Stephan Mueller 2014-11-12 404 * arbitrary value, but in the usual case, this contains the
0d7f488f0 Stephan Mueller 2014-11-12 405 * name of the chip or provider and the name of the
0d7f488f0 Stephan Mueller 2014-11-12 406 * transformation algorithm.
0d7f488f0 Stephan Mueller 2014-11-12 407 * @cra_type: Type of the cryptographic transformation. This is a pointer to
0d7f488f0 Stephan Mueller 2014-11-12 408 * struct crypto_type, which implements callbacks common for all
12f7c14aa Masanari Iida 2015-06-04 409 * transformation types. There are multiple options:
0d7f488f0 Stephan Mueller 2014-11-12 410 * &crypto_blkcipher_type, &crypto_ablkcipher_type,
b0d955ba4 Herbert Xu 2015-08-14 411 * &crypto_ahash_type, &crypto_rng_type.
0d7f488f0 Stephan Mueller 2014-11-12 412 * This field might be empty. In that case, there are no common
0d7f488f0 Stephan Mueller 2014-11-12 413 * callbacks. This is the case for: cipher, compress, shash.
0d7f488f0 Stephan Mueller 2014-11-12 414 * @cra_u: Callbacks implementing the transformation. This is a union of
0d7f488f0 Stephan Mueller 2014-11-12 415 * multiple structures. Depending on the type of transformation selected
0d7f488f0 Stephan Mueller 2014-11-12 416 * by @cra_type and @cra_flags above, the associated structure must be
0d7f488f0 Stephan Mueller 2014-11-12 417 * filled with callbacks. This field might be empty. This is the case
0d7f488f0 Stephan Mueller 2014-11-12 418 * for ahash, shash.
0d7f488f0 Stephan Mueller 2014-11-12 419 * @cra_init: Initialize the cryptographic transformation object. This function
0d7f488f0 Stephan Mueller 2014-11-12 420 * is used to initialize the cryptographic transformation object.
0d7f488f0 Stephan Mueller 2014-11-12 421 * This function is called only once at the instantiation time, right
0d7f488f0 Stephan Mueller 2014-11-12 422 * after the transformation context was allocated. In case the
0d7f488f0 Stephan Mueller 2014-11-12 423 * cryptographic hardware has some special requirements which need to
0d7f488f0 Stephan Mueller 2014-11-12 424 * be handled by software, this function shall check for the precise
0d7f488f0 Stephan Mueller 2014-11-12 425 * requirement of the transformation and put any software fallbacks
0d7f488f0 Stephan Mueller 2014-11-12 426 * in place.
0d7f488f0 Stephan Mueller 2014-11-12 427 * @cra_exit: Deinitialize the cryptographic transformation object. This is a
0d7f488f0 Stephan Mueller 2014-11-12 428 * counterpart to @cra_init, used to remove various changes set in
0d7f488f0 Stephan Mueller 2014-11-12 429 * @cra_init.
0d7f488f0 Stephan Mueller 2014-11-12 430 * @cra_module: Owner of this transformation implementation. Set to THIS_MODULE
0d7f488f0 Stephan Mueller 2014-11-12 431 * @cra_list: internally used
0d7f488f0 Stephan Mueller 2014-11-12 432 * @cra_users: internally used
0d7f488f0 Stephan Mueller 2014-11-12 433 * @cra_refcnt: internally used
0d7f488f0 Stephan Mueller 2014-11-12 434 * @cra_destroy: internally used
0d7f488f0 Stephan Mueller 2014-11-12 435 *
0d7f488f0 Stephan Mueller 2014-11-12 436 * The struct crypto_alg describes a generic Crypto API algorithm and is common
0d7f488f0 Stephan Mueller 2014-11-12 437 * for all of the transformations. Any variable not documented here shall not
0d7f488f0 Stephan Mueller 2014-11-12 438 * be used by a cipher implementation as it is internal to the Crypto API.
0d7f488f0 Stephan Mueller 2014-11-12 439 */
^1da177e4 Linus Torvalds 2005-04-16 440 struct crypto_alg {
^1da177e4 Linus Torvalds 2005-04-16 441 struct list_head cra_list;
6bfd48096 Herbert Xu 2006-09-21 442 struct list_head cra_users;
6bfd48096 Herbert Xu 2006-09-21 443
^1da177e4 Linus Torvalds 2005-04-16 444 u32 cra_flags;
^1da177e4 Linus Torvalds 2005-04-16 445 unsigned int cra_blocksize;
^1da177e4 Linus Torvalds 2005-04-16 446 unsigned int cra_ctxsize;
954773779 Herbert Xu 2005-07-06 447 unsigned int cra_alignmask;
5cb1454b8 Herbert Xu 2005-11-05 448
5cb1454b8 Herbert Xu 2005-11-05 449 int cra_priority;
6521f3027 Herbert Xu 2006-08-06 450 atomic_t cra_refcnt;
5cb1454b8 Herbert Xu 2005-11-05 451
d913ea0d6 Herbert Xu 2006-05-21 452 char cra_name[CRYPTO_MAX_ALG_NAME];
d913ea0d6 Herbert Xu 2006-05-21 453 char cra_driver_name[CRYPTO_MAX_ALG_NAME];
^1da177e4 Linus Torvalds 2005-04-16 454
e853c3cfa Herbert Xu 2006-08-22 455 const struct crypto_type *cra_type;
e853c3cfa Herbert Xu 2006-08-22 456
^1da177e4 Linus Torvalds 2005-04-16 457 union {
b5b7f0886 Herbert Xu 2007-04-16 458 struct ablkcipher_alg ablkcipher;
5cde0af2a Herbert Xu 2006-08-22 459 struct blkcipher_alg blkcipher;
^1da177e4 Linus Torvalds 2005-04-16 460 struct cipher_alg cipher;
^1da177e4 Linus Torvalds 2005-04-16 461 struct compress_alg compress;
^1da177e4 Linus Torvalds 2005-04-16 462 } cra_u;
^1da177e4 Linus Torvalds 2005-04-16 463
c7fc05992 Herbert Xu 2006-05-24 464 int (*cra_init)(struct crypto_tfm *tfm);
c7fc05992 Herbert Xu 2006-05-24 465 void (*cra_exit)(struct crypto_tfm *tfm);
6521f3027 Herbert Xu 2006-08-06 466 void (*cra_destroy)(struct crypto_alg *alg);
c7fc05992 Herbert Xu 2006-05-24 467
^1da177e4 Linus Torvalds 2005-04-16 468 struct module *cra_module;
edf18b910 Herbert Xu 2015-06-18 @469 } CRYPTO_MINALIGN_ATTR;
^1da177e4 Linus Torvalds 2005-04-16 470
:::::: The code at line 469 was first introduced by commit
:::::: edf18b9108f5025f9e83b2c167c9122954acbc62 crypto: api - Add CRYPTO_MINALIGN_ATTR to struct crypto_alg
:::::: TO: Herbert Xu <herbert@gondor.apana.org.au>
:::::: CC: Herbert Xu <herbert@gondor.apana.org.au>
---
0-DAY kernel test infrastructure Open Source Technology Center
https://lists.01.org/pipermail/kbuild-all Intel Corporation
[-- Attachment #2: .config.gz --]
[-- Type: application/gzip, Size: 6843 bytes --]
^ permalink raw reply [flat|nested] 28+ messages in thread
* [PATCH v4 15/18] scripts: kernel-doc: handle nested struct function arguments
2017-12-18 12:30 [PATCH v4 00/18] kernel-doc: add supported to document nested structs Mauro Carvalho Chehab
` (13 preceding siblings ...)
2017-12-18 12:30 ` [PATCH v4 14/18] scripts: kernel-doc: print the declaration name on warnings Mauro Carvalho Chehab
@ 2017-12-18 12:30 ` Mauro Carvalho Chehab
2017-12-21 6:48 ` kbuild test robot
2017-12-18 12:30 ` [PATCH v4 16/18] scripts: kernel-doc: improve nested logic to handle multiple identifiers Mauro Carvalho Chehab
` (3 subsequent siblings)
18 siblings, 1 reply; 28+ messages in thread
From: Mauro Carvalho Chehab @ 2017-12-18 12:30 UTC (permalink / raw)
To: Linux Media Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Linux Doc Mailing List
Function arguments are different than usual ones. So, an
special logic is needed in order to handle such arguments
on nested structs.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
scripts/kernel-doc | 38 ++++++++++++++++++++++++++------------
1 file changed, 26 insertions(+), 12 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index c97b89f47795..5d03c9086323 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1041,18 +1041,32 @@ sub dump_struct($$) {
$id =~ s/^\*+//;
foreach my $arg (split /;/, $content) {
next if ($arg =~ m/^\s*$/);
- my $type = $arg;
- my $name = $arg;
- $type =~ s/\s\S+$//;
- $name =~ s/.*\s//;
- $name =~ s/[:\[].*//;
- $name =~ s/^\*+//;
- next if (($name =~ m/^\s*$/));
- if ($id =~ m/^\s*$/) {
- # anonymous struct/union
- $newmember .= "$type $name;";
+ if ($arg =~ m/^([^\(]+\(\*?\s*)([\w\.]*)(\s*\).*)/) {
+ # pointer-to-function
+ my $type = $1;
+ my $name = $2;
+ my $extra = $3;
+ next if (!$name);
+ if ($id =~ m/^\s*$/) {
+ # anonymous struct/union
+ $newmember .= "$type$name$extra;";
+ } else {
+ $newmember .= "$type$id.$name$extra;";
+ }
} else {
- $newmember .= "$type $id.$name;";
+ my $type = $arg;
+ my $name = $arg;
+ $type =~ s/\s\S+$//;
+ $name =~ s/.*\s+//;
+ $name =~ s/[:\[].*//;
+ $name =~ s/^\*+//;
+ next if (($name =~ m/^\s*$/));
+ if ($id =~ m/^\s*$/) {
+ # anonymous struct/union
+ $newmember .= "$type $name;";
+ } else {
+ $newmember .= "$type $id.$name;";
+ }
}
}
$members =~ s/(struct|union)([^{};]+){([^{}]*)}([^{}\;]*)\;/$newmember/;
@@ -1250,7 +1264,7 @@ sub create_parameterlist($$$$) {
} elsif ($arg =~ m/\(.+\)\s*\(/) {
# pointer-to-function
$arg =~ tr/#/,/;
- $arg =~ m/[^\(]+\(\*?\s*(\w*)\s*\)/;
+ $arg =~ m/[^\(]+\(\*?\s*([\w\.]*)\s*\)/;
$param = $1;
$type = $arg;
$type =~ s/([^\(]+\(\*?)\s*$param/$1/;
--
2.14.3
^ permalink raw reply related [flat|nested] 28+ messages in thread* Re: [PATCH v4 15/18] scripts: kernel-doc: handle nested struct function arguments
2017-12-18 12:30 ` [PATCH v4 15/18] scripts: kernel-doc: handle nested struct function arguments Mauro Carvalho Chehab
@ 2017-12-21 6:48 ` kbuild test robot
0 siblings, 0 replies; 28+ messages in thread
From: kbuild test robot @ 2017-12-21 6:48 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: kbuild-all, Linux Media Mailing List, Jonathan Corbet,
Mauro Carvalho Chehab, Mauro Carvalho Chehab,
Linux Doc Mailing List
[-- Attachment #1: Type: text/plain, Size: 50301 bytes --]
Hi Mauro,
I love your patch! Perhaps something to improve:
[auto build test WARNING on lwn/docs-next]
[also build test WARNING on v4.15-rc4 next-20171221]
[cannot apply to linus/master]
[if your patch is applied to the wrong git tree, please drop us a note to help improve the system]
url: https://github.com/0day-ci/linux/commits/Mauro-Carvalho-Chehab/kernel-doc-add-supported-to-document-nested-structs/20171221-055609
base: git://git.lwn.net/linux-2.6 docs-next
reproduce: make htmldocs
All warnings (new ones prefixed by >>):
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
drivers/media/dvb-core/dmxdev.h:145: warning: Function parameter or member 'filter.sec' not described in 'dmxdev_filter'
drivers/media/dvb-core/dmxdev.h:145: warning: Function parameter or member 'feed.ts' not described in 'dmxdev_filter'
drivers/media/dvb-core/dmxdev.h:145: warning: Function parameter or member 'feed.sec' not described in 'dmxdev_filter'
drivers/media/dvb-core/dmxdev.h:145: warning: Function parameter or member 'params.sec' not described in 'dmxdev_filter'
drivers/media/dvb-core/dmxdev.h:145: warning: Function parameter or member 'params.pes' not described in 'dmxdev_filter'
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
drivers/media/dvb-core/dvb_demux.h:153: warning: Function parameter or member 'feed.ts' not described in 'dvb_demux_feed'
drivers/media/dvb-core/dvb_demux.h:153: warning: Function parameter or member 'feed.sec' not described in 'dvb_demux_feed'
drivers/media/dvb-core/dvb_demux.h:153: warning: Function parameter or member 'cb.ts' not described in 'dvb_demux_feed'
drivers/media/dvb-core/dvb_demux.h:153: warning: Function parameter or member 'cb.sec' not described in 'dvb_demux_feed'
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
include/media/media-entity.h:102: warning: Function parameter or member 'stack.entity' not described in 'media_graph'
include/media/media-entity.h:102: warning: Function parameter or member 'stack.link' not described in 'media_graph'
include/media/media-entity.h:290: warning: Function parameter or member 'info.dev' not described in 'media_entity'
include/media/media-entity.h:290: warning: Function parameter or member 'info.dev.major' not described in 'media_entity'
include/media/media-entity.h:290: warning: Function parameter or member 'info.dev.minor' not described in 'media_entity'
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
include/media/v4l2-async.h:80: warning: Function parameter or member 'match.fwnode' not described in 'v4l2_async_subdev'
include/media/v4l2-async.h:80: warning: Function parameter or member 'match.fwnode.fwnode' not described in 'v4l2_async_subdev'
include/media/v4l2-async.h:80: warning: Function parameter or member 'match.device_name' not described in 'v4l2_async_subdev'
include/media/v4l2-async.h:80: warning: Function parameter or member 'match.device_name.name' not described in 'v4l2_async_subdev'
include/media/v4l2-async.h:80: warning: Function parameter or member 'match.i2c' not described in 'v4l2_async_subdev'
include/media/v4l2-async.h:80: warning: Function parameter or member 'match.i2c.adapter_id' not described in 'v4l2_async_subdev'
include/media/v4l2-async.h:80: warning: Function parameter or member 'match.i2c.address' not described in 'v4l2_async_subdev'
include/media/v4l2-async.h:80: warning: Function parameter or member 'match.custom' not described in 'v4l2_async_subdev'
>> include/media/v4l2-async.h:80: warning: Function parameter or member 'match.custom.match' not described in 'v4l2_async_subdev'
include/media/v4l2-async.h:80: warning: Function parameter or member 'match.custom.priv' not described in 'v4l2_async_subdev'
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
include/media/v4l2-ctrls.h:233: warning: Function parameter or member 'qmenu_int' not described in 'v4l2_ctrl'
include/media/v4l2-ctrls.h:233: warning: Function parameter or member 'cur.val' not described in 'v4l2_ctrl'
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
include/media/v4l2-fwnode.h:102: warning: Function parameter or member 'bus.parallel' not described in 'v4l2_fwnode_endpoint'
include/media/v4l2-fwnode.h:102: warning: Function parameter or member 'bus.mipi_csi1' not described in 'v4l2_fwnode_endpoint'
include/media/v4l2-fwnode.h:102: warning: Function parameter or member 'bus.mipi_csi2' not described in 'v4l2_fwnode_endpoint'
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
include/media/v4l2-async.h:80: warning: Function parameter or member 'match.fwnode' not described in 'v4l2_async_subdev'
include/media/v4l2-async.h:80: warning: Function parameter or member 'match.fwnode.fwnode' not described in 'v4l2_async_subdev'
include/media/v4l2-async.h:80: warning: Function parameter or member 'match.device_name' not described in 'v4l2_async_subdev'
include/media/v4l2-async.h:80: warning: Function parameter or member 'match.device_name.name' not described in 'v4l2_async_subdev'
include/media/v4l2-async.h:80: warning: Function parameter or member 'match.i2c' not described in 'v4l2_async_subdev'
include/media/v4l2-async.h:80: warning: Function parameter or member 'match.i2c.adapter_id' not described in 'v4l2_async_subdev'
include/media/v4l2-async.h:80: warning: Function parameter or member 'match.i2c.address' not described in 'v4l2_async_subdev'
include/media/v4l2-async.h:80: warning: Function parameter or member 'match.custom' not described in 'v4l2_async_subdev'
>> include/media/v4l2-async.h:80: warning: Function parameter or member 'match.custom.match' not described in 'v4l2_async_subdev'
include/media/v4l2-async.h:80: warning: Function parameter or member 'match.custom.priv' not described in 'v4l2_async_subdev'
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
include/media/videobuf2-core.h:184: warning: Function parameter or member 'm.offset' not described in 'vb2_plane'
include/media/videobuf2-core.h:184: warning: Function parameter or member 'm.userptr' not described in 'vb2_plane'
include/media/videobuf2-core.h:184: warning: Function parameter or member 'm.fd' not described in 'vb2_plane'
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
include/uapi/linux/dvb/frontend.h:807: warning: Function parameter or member 'uvalue' not described in 'dtv_stats'
include/uapi/linux/dvb/frontend.h:807: warning: Function parameter or member 'svalue' not described in 'dtv_stats'
include/uapi/linux/dvb/frontend.h:859: warning: Function parameter or member 'u.data' not described in 'dtv_property'
include/uapi/linux/dvb/frontend.h:859: warning: Function parameter or member 'u.st' not described in 'dtv_property'
include/uapi/linux/dvb/frontend.h:859: warning: Function parameter or member 'u.buffer' not described in 'dtv_property'
include/uapi/linux/dvb/frontend.h:859: warning: Function parameter or member 'u.buffer.data' not described in 'dtv_property'
include/uapi/linux/dvb/frontend.h:859: warning: Function parameter or member 'u.buffer.len' not described in 'dtv_property'
include/uapi/linux/dvb/frontend.h:859: warning: Function parameter or member 'u.buffer.reserved1' not described in 'dtv_property'
include/uapi/linux/dvb/frontend.h:859: warning: Function parameter or member 'u.buffer.reserved2' not described in 'dtv_property'
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
include/linux/skbuff.h:846: warning: Function parameter or member 'dev_scratch' not described in 'sk_buff'
include/linux/skbuff.h:846: warning: Function parameter or member 'skb_mstamp' not described in 'sk_buff'
include/linux/skbuff.h:846: warning: Function parameter or member '__cloned_offset' not described in 'sk_buff'
include/linux/skbuff.h:846: warning: Function parameter or member 'head_frag' not described in 'sk_buff'
include/linux/skbuff.h:846: warning: Function parameter or member '__unused' not described in 'sk_buff'
include/linux/skbuff.h:846: warning: Function parameter or member '__pkt_type_offset' not described in 'sk_buff'
include/linux/skbuff.h:846: warning: Function parameter or member 'pfmemalloc' not described in 'sk_buff'
include/linux/skbuff.h:846: warning: Function parameter or member 'encapsulation' not described in 'sk_buff'
include/linux/skbuff.h:846: warning: Function parameter or member 'encap_hdr_csum' not described in 'sk_buff'
include/linux/skbuff.h:846: warning: Function parameter or member 'csum_valid' not described in 'sk_buff'
include/linux/skbuff.h:846: warning: Function parameter or member 'csum_complete_sw' not described in 'sk_buff'
include/linux/skbuff.h:846: warning: Function parameter or member 'csum_level' not described in 'sk_buff'
include/linux/skbuff.h:846: warning: Function parameter or member 'inner_protocol_type' not described in 'sk_buff'
include/linux/skbuff.h:846: warning: Function parameter or member 'remcsum_offload' not described in 'sk_buff'
include/linux/skbuff.h:846: warning: Function parameter or member 'offload_fwd_mark' not described in 'sk_buff'
include/linux/skbuff.h:846: warning: Function parameter or member 'offload_mr_fwd_mark' not described in 'sk_buff'
include/linux/skbuff.h:846: warning: Function parameter or member 'sender_cpu' not described in 'sk_buff'
include/linux/skbuff.h:846: warning: Function parameter or member 'reserved_tailroom' not described in 'sk_buff'
include/linux/skbuff.h:846: warning: Function parameter or member 'inner_ipproto' not described in 'sk_buff'
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
include/net/sock.h:233: warning: Function parameter or member 'skc_addrpair' not described in 'sock_common'
include/net/sock.h:233: warning: Function parameter or member 'skc_portpair' not described in 'sock_common'
include/net/sock.h:233: warning: Function parameter or member 'skc_ipv6only' not described in 'sock_common'
include/net/sock.h:233: warning: Function parameter or member 'skc_net_refcnt' not described in 'sock_common'
include/net/sock.h:233: warning: Function parameter or member 'skc_v6_daddr' not described in 'sock_common'
include/net/sock.h:233: warning: Function parameter or member 'skc_v6_rcv_saddr' not described in 'sock_common'
include/net/sock.h:233: warning: Function parameter or member 'skc_cookie' not described in 'sock_common'
include/net/sock.h:233: warning: Function parameter or member 'skc_listener' not described in 'sock_common'
include/net/sock.h:233: warning: Function parameter or member 'skc_tw_dr' not described in 'sock_common'
include/net/sock.h:233: warning: Function parameter or member 'skc_rcv_wnd' not described in 'sock_common'
include/net/sock.h:233: warning: Function parameter or member 'skc_tw_rcv_nxt' not described in 'sock_common'
include/net/sock.h:486: warning: Function parameter or member 'sk_backlog.rmem_alloc' not described in 'sock'
include/net/sock.h:486: warning: Function parameter or member 'sk_backlog.len' not described in 'sock'
include/net/sock.h:486: warning: Function parameter or member 'sk_backlog.head' not described in 'sock'
include/net/sock.h:486: warning: Function parameter or member 'sk_backlog.tail' not described in 'sock'
include/net/sock.h:486: warning: Function parameter or member 'sk_wq_raw' not described in 'sock'
include/net/sock.h:486: warning: Function parameter or member 'tcp_rtx_queue' not described in 'sock'
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1072.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.30), passed through in regex; marked by <-- HERE in m/(struct|union)([^{};]+){ <-- HERE ([^{}]*)}([^{}\;]*)\;/ at scripts/kernel-doc line 1036.
vim +80 include/media/v4l2-async.h
e9e310491 Guennadi Liakhovetski 2013-01-08 45
e9e310491 Guennadi Liakhovetski 2013-01-08 46 /**
e9e310491 Guennadi Liakhovetski 2013-01-08 47 * struct v4l2_async_subdev - sub-device descriptor, as known to a bridge
f8b273770 Mauro Carvalho Chehab 2015-08-22 48 *
f8b273770 Mauro Carvalho Chehab 2015-08-22 49 * @match_type: type of match that will be used
e9e310491 Guennadi Liakhovetski 2013-01-08 50 * @match: union of per-bus type matching data sets
e9e310491 Guennadi Liakhovetski 2013-01-08 51 * @list: used to link struct v4l2_async_subdev objects, waiting to be
e9e310491 Guennadi Liakhovetski 2013-01-08 52 * probed, to a notifier->waiting list
9ca465312 Sakari Ailus 2017-08-17 53 *
9ca465312 Sakari Ailus 2017-08-17 54 * When this struct is used as a member in a driver specific struct,
9ca465312 Sakari Ailus 2017-08-17 55 * the driver specific struct shall contain the &struct
9ca465312 Sakari Ailus 2017-08-17 56 * v4l2_async_subdev as its first member.
e9e310491 Guennadi Liakhovetski 2013-01-08 57 */
e9e310491 Guennadi Liakhovetski 2013-01-08 58 struct v4l2_async_subdev {
cfca7644d Sylwester Nawrocki 2013-07-19 59 enum v4l2_async_match_type match_type;
e9e310491 Guennadi Liakhovetski 2013-01-08 60 union {
e9e310491 Guennadi Liakhovetski 2013-01-08 61 struct {
ecdf0cfe7 Sakari Ailus 2016-08-16 62 struct fwnode_handle *fwnode;
ecdf0cfe7 Sakari Ailus 2016-08-16 63 } fwnode;
ecdf0cfe7 Sakari Ailus 2016-08-16 64 struct {
e9e310491 Guennadi Liakhovetski 2013-01-08 65 const char *name;
cfca7644d Sylwester Nawrocki 2013-07-19 66 } device_name;
e9e310491 Guennadi Liakhovetski 2013-01-08 67 struct {
e9e310491 Guennadi Liakhovetski 2013-01-08 68 int adapter_id;
e9e310491 Guennadi Liakhovetski 2013-01-08 69 unsigned short address;
e9e310491 Guennadi Liakhovetski 2013-01-08 70 } i2c;
e9e310491 Guennadi Liakhovetski 2013-01-08 71 struct {
e9e310491 Guennadi Liakhovetski 2013-01-08 72 bool (*match)(struct device *,
e9e310491 Guennadi Liakhovetski 2013-01-08 73 struct v4l2_async_subdev *);
e9e310491 Guennadi Liakhovetski 2013-01-08 74 void *priv;
e9e310491 Guennadi Liakhovetski 2013-01-08 75 } custom;
e9e310491 Guennadi Liakhovetski 2013-01-08 76 } match;
e9e310491 Guennadi Liakhovetski 2013-01-08 77
e9e310491 Guennadi Liakhovetski 2013-01-08 78 /* v4l2-async core private: not to be used by drivers */
e9e310491 Guennadi Liakhovetski 2013-01-08 79 struct list_head list;
e9e310491 Guennadi Liakhovetski 2013-01-08 @80 };
e9e310491 Guennadi Liakhovetski 2013-01-08 81
:::::: The code at line 80 was first introduced by commit
:::::: e9e310491bdbc8c0f33ea0e2ce65eff345a01f71 [media] V4L2: support asynchronous subdevice registration
:::::: TO: Guennadi Liakhovetski <g.liakhovetski@gmx.de>
:::::: CC: Mauro Carvalho Chehab <mchehab@redhat.com>
---
0-DAY kernel test infrastructure Open Source Technology Center
https://lists.01.org/pipermail/kbuild-all Intel Corporation
[-- Attachment #2: .config.gz --]
[-- Type: application/gzip, Size: 6843 bytes --]
^ permalink raw reply [flat|nested] 28+ messages in thread
* [PATCH v4 16/18] scripts: kernel-doc: improve nested logic to handle multiple identifiers
2017-12-18 12:30 [PATCH v4 00/18] kernel-doc: add supported to document nested structs Mauro Carvalho Chehab
` (14 preceding siblings ...)
2017-12-18 12:30 ` [PATCH v4 15/18] scripts: kernel-doc: handle nested struct function arguments Mauro Carvalho Chehab
@ 2017-12-18 12:30 ` Mauro Carvalho Chehab
2017-12-21 9:57 ` kbuild test robot
2018-02-14 16:07 ` Jani Nikula
2017-12-18 12:30 ` [PATCH v4 17/18] scripts: kernel-doc: apply filtering rules to warnings Mauro Carvalho Chehab
` (2 subsequent siblings)
18 siblings, 2 replies; 28+ messages in thread
From: Mauro Carvalho Chehab @ 2017-12-18 12:30 UTC (permalink / raw)
To: Linux Media Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Linux Doc Mailing List
It is possible to use nested structs like:
struct {
struct {
void *arg1;
} st1, st2, *st3, st4;
};
Handling it requires to split each parameter. Change the logic
to allow such definitions.
In order to test the new nested logic, the following file
was used to test
<code>
struct foo { int a; }; /* Just to avoid errors if compiled */
/**
* struct my_struct - a struct with nested unions and structs
* @arg1: first argument of anonymous union/anonymous struct
* @arg2: second argument of anonymous union/anonymous struct
* @arg1b: first argument of anonymous union/anonymous struct
* @arg2b: second argument of anonymous union/anonymous struct
* @arg3: third argument of anonymous union/anonymous struct
* @arg4: fourth argument of anonymous union/anonymous struct
* @bar.st1.arg1: first argument of struct st1 on union bar
* @bar.st1.arg2: second argument of struct st1 on union bar
* @bar.st1.bar1: bar1 at st1
* @bar.st1.bar2: bar2 at st1
* @bar.st2.arg1: first argument of struct st2 on union bar
* @bar.st2.arg2: second argument of struct st2 on union bar
* @bar.st3.arg2: second argument of struct st3 on union bar
* @f1: nested function on anonimous union/struct
* @bar.st2.f2: nested function on named union/struct
*/
struct my_struct {
/* Anonymous union/struct*/
union {
struct {
char arg1 : 1;
char arg2 : 3;
};
struct {
int arg1b;
int arg2b;
};
struct {
void *arg3;
int arg4;
int (*f1)(char foo, int bar);
};
};
union {
struct {
int arg1;
int arg2;
struct foo bar1, *bar2;
} st1; /* bar.st1 is undocumented, cause a warning */
struct {
void *arg1; /* bar.st3.arg1 is undocumented, cause a warning */
int arg2;
int (*f2)(char foo, int bar); /* bar.st3.fn2 is undocumented, cause a warning */
} st2, st3, *st4;
int (*f3)(char foo, int bar); /* f3 is undocumented, cause a warning */
} bar; /* bar is undocumented, cause a warning */
/* private: */
int undoc_privat; /* is undocumented but private, no warning */
/* public: */
int undoc_public; /* is undocumented, cause a warning */
};
</code>
It produces the following warnings, as expected:
test2.h:57: warning: Function parameter or member 'bar' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3.arg1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3.f2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.arg1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.arg2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.f2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.f3' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'undoc_public' not described in 'my_struct'
Suggested-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
scripts/kernel-doc | 69 ++++++++++++++++++++++++++++++++++--------------------
1 file changed, 44 insertions(+), 25 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 5d03c9086323..0bda21d9d3f2 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1030,15 +1030,16 @@ sub dump_struct($$) {
my $declaration = $members;
# Split nested struct/union elements as newer ones
- my $cont = 1;
- while ($cont) {
- $cont = 0;
- while ($members =~ m/(struct|union)([^{};]+){([^{}]*)}([^{}\;]*)\;/) {
- my $newmember = "$1 $4;";
- my $id = $4;
- my $content = $3;
+ while ($members =~ m/(struct|union)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;/) {
+ my $newmember;
+ my $maintype = $1;
+ my $ids = $4;
+ my $content = $3;
+ foreach my $id(split /,/, $ids) {
+ $newmember .= "$maintype $id; ";
+
$id =~ s/[:\[].*//;
- $id =~ s/^\*+//;
+ $id =~ s/^\s*\**(\S+)\s*/$1/;
foreach my $arg (split /;/, $content) {
next if ($arg =~ m/^\s*$/);
if ($arg =~ m/^([^\(]+\(\*?\s*)([\w\.]*)(\s*\).*)/) {
@@ -1049,30 +1050,48 @@ sub dump_struct($$) {
next if (!$name);
if ($id =~ m/^\s*$/) {
# anonymous struct/union
- $newmember .= "$type$name$extra;";
+ $newmember .= "$type$name$extra; ";
} else {
- $newmember .= "$type$id.$name$extra;";
+ $newmember .= "$type$id.$name$extra; ";
}
} else {
- my $type = $arg;
- my $name = $arg;
- $type =~ s/\s\S+$//;
- $name =~ s/.*\s+//;
- $name =~ s/[:\[].*//;
- $name =~ s/^\*+//;
- next if (($name =~ m/^\s*$/));
- if ($id =~ m/^\s*$/) {
- # anonymous struct/union
- $newmember .= "$type $name;";
+ my $type;
+ my $names;
+ $arg =~ s/^\s+//;
+ $arg =~ s/\s+$//;
+ # Handle bitmaps
+ $arg =~ s/:\s*\d+\s*//g;
+ # Handle arrays
+ $arg =~ s/\[\S+\]//g;
+ # The type may have multiple words,
+ # and multiple IDs can be defined, like:
+ # const struct foo, *bar, foobar
+ # So, we remove spaces when parsing the
+ # names, in order to match just names
+ # and commas for the names
+ $arg =~ s/\s*,\s*/,/g;
+ if ($arg =~ m/(.*)\s+([\S+,]+)/) {
+ $type = $1;
+ $names = $2;
} else {
- $newmember .= "$type $id.$name;";
+ $newmember .= "$arg; ";
+ next;
+ }
+ foreach my $name (split /,/, $names) {
+ $name =~ s/^\s*\**(\S+)\s*/$1/;
+ next if (($name =~ m/^\s*$/));
+ if ($id =~ m/^\s*$/) {
+ # anonymous struct/union
+ $newmember .= "$type $name; ";
+ } else {
+ $newmember .= "$type $id.$name; ";
+ }
}
}
}
- $members =~ s/(struct|union)([^{};]+){([^{}]*)}([^{}\;]*)\;/$newmember/;
- $cont = 1;
- };
- };
+ }
+ $members =~ s/(struct|union)([^\{\};]+)\{([^\{\}]*)}([^\{\}\;]*)\;/$newmember/;
+ }
# Ignore other nested elements, like enums
$members =~ s/({[^\{\}]*})//g;
--
2.14.3
^ permalink raw reply related [flat|nested] 28+ messages in thread* Re: [PATCH v4 16/18] scripts: kernel-doc: improve nested logic to handle multiple identifiers
2017-12-18 12:30 ` [PATCH v4 16/18] scripts: kernel-doc: improve nested logic to handle multiple identifiers Mauro Carvalho Chehab
@ 2017-12-21 9:57 ` kbuild test robot
2018-02-14 16:07 ` Jani Nikula
1 sibling, 0 replies; 28+ messages in thread
From: kbuild test robot @ 2017-12-21 9:57 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: kbuild-all, Linux Media Mailing List, Jonathan Corbet,
Mauro Carvalho Chehab, Mauro Carvalho Chehab,
Linux Doc Mailing List
[-- Attachment #1: Type: text/plain, Size: 25287 bytes --]
Hi Mauro,
I love your patch! Perhaps something to improve:
[auto build test WARNING on lwn/docs-next]
[also build test WARNING on v4.15-rc4 next-20171221]
[cannot apply to linus/master]
[if your patch is applied to the wrong git tree, please drop us a note to help improve the system]
url: https://github.com/0day-ci/linux/commits/Mauro-Carvalho-Chehab/kernel-doc-add-supported-to-document-nested-structs/20171221-055609
base: git://git.lwn.net/linux-2.6 docs-next
reproduce: make htmldocs
All warnings (new ones prefixed by >>):
WARNING: convert(1) not found, for SVG to PDF conversion install ImageMagick (https://www.imagemagick.org)
include/crypto/hash.h:89: warning: duplicate section name 'Note'
include/crypto/hash.h:95: warning: duplicate section name 'Note'
include/crypto/hash.h:102: warning: duplicate section name 'Note'
include/crypto/hash.h:89: warning: duplicate section name 'Note'
include/crypto/hash.h:95: warning: duplicate section name 'Note'
include/crypto/hash.h:102: warning: duplicate section name 'Note'
include/crypto/hash.h:89: warning: duplicate section name 'Note'
include/crypto/hash.h:95: warning: duplicate section name 'Note'
include/crypto/hash.h:102: warning: duplicate section name 'Note'
include/crypto/hash.h:89: warning: duplicate section name 'Note'
include/crypto/hash.h:95: warning: duplicate section name 'Note'
include/crypto/hash.h:102: warning: duplicate section name 'Note'
include/crypto/hash.h:89: warning: duplicate section name 'Note'
include/crypto/hash.h:95: warning: duplicate section name 'Note'
include/crypto/hash.h:102: warning: duplicate section name 'Note'
include/crypto/hash.h:89: warning: duplicate section name 'Note'
include/crypto/hash.h:95: warning: duplicate section name 'Note'
include/crypto/hash.h:102: warning: duplicate section name 'Note'
include/crypto/hash.h:89: warning: duplicate section name 'Note'
include/crypto/hash.h:95: warning: duplicate section name 'Note'
include/crypto/hash.h:102: warning: duplicate section name 'Note'
include/crypto/hash.h:89: warning: duplicate section name 'Note'
include/crypto/hash.h:95: warning: duplicate section name 'Note'
include/crypto/hash.h:102: warning: duplicate section name 'Note'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.ablkcipher' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.blkcipher' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.cipher' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.compress' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.ablkcipher' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.blkcipher' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.cipher' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.compress' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.ablkcipher' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.blkcipher' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.cipher' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.compress' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.ablkcipher' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.blkcipher' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.cipher' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.compress' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.ablkcipher' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.blkcipher' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.cipher' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.compress' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.ablkcipher' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.blkcipher' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.cipher' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.compress' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.ablkcipher' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.blkcipher' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.cipher' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.compress' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.ablkcipher' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.blkcipher' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.cipher' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.compress' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.ablkcipher' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.blkcipher' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.cipher' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.compress' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.ablkcipher' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.blkcipher' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.cipher' not described in 'crypto_alg'
include/linux/crypto.h:469: warning: Function parameter or member 'cra_u.compress' not described in 'crypto_alg'
include/net/cfg80211.h:2056: warning: Function parameter or member 'param.band_pref' not described in 'cfg80211_bss_selection'
include/net/cfg80211.h:2056: warning: Function parameter or member 'param.adjust' not described in 'cfg80211_bss_selection'
include/net/cfg80211.h:3278: warning: Excess enum value 'WIPHY_FLAG_SUPPORTS_SCHED_SCAN' description in 'wiphy_flags'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ibss' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.connect' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.keys' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ie' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ie_len' not described in 'wireless_dev'
>> include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.bssid' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.prev_bssid' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ssid' not described in 'wireless_dev'
>> include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.default_key' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.default_mgmt_key' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.prev_bssid_valid' not described in 'wireless_dev'
include/net/cfg80211.h:2056: warning: Function parameter or member 'param.band_pref' not described in 'cfg80211_bss_selection'
include/net/cfg80211.h:2056: warning: Function parameter or member 'param.adjust' not described in 'cfg80211_bss_selection'
include/net/cfg80211.h:3278: warning: Excess enum value 'WIPHY_FLAG_SUPPORTS_SCHED_SCAN' description in 'wiphy_flags'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ibss' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.connect' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.keys' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ie' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ie_len' not described in 'wireless_dev'
>> include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.bssid' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.prev_bssid' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ssid' not described in 'wireless_dev'
>> include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.default_key' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.default_mgmt_key' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.prev_bssid_valid' not described in 'wireless_dev'
include/net/cfg80211.h:2056: warning: Function parameter or member 'param.band_pref' not described in 'cfg80211_bss_selection'
include/net/cfg80211.h:2056: warning: Function parameter or member 'param.adjust' not described in 'cfg80211_bss_selection'
include/net/cfg80211.h:3278: warning: Excess enum value 'WIPHY_FLAG_SUPPORTS_SCHED_SCAN' description in 'wiphy_flags'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ibss' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.connect' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.keys' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ie' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ie_len' not described in 'wireless_dev'
>> include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.bssid' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.prev_bssid' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ssid' not described in 'wireless_dev'
>> include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.default_key' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.default_mgmt_key' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.prev_bssid_valid' not described in 'wireless_dev'
include/net/cfg80211.h:2056: warning: Function parameter or member 'param.band_pref' not described in 'cfg80211_bss_selection'
include/net/cfg80211.h:2056: warning: Function parameter or member 'param.adjust' not described in 'cfg80211_bss_selection'
include/net/cfg80211.h:3278: warning: Excess enum value 'WIPHY_FLAG_SUPPORTS_SCHED_SCAN' description in 'wiphy_flags'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ibss' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.connect' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.keys' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ie' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ie_len' not described in 'wireless_dev'
>> include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.bssid' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.prev_bssid' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ssid' not described in 'wireless_dev'
>> include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.default_key' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.default_mgmt_key' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.prev_bssid_valid' not described in 'wireless_dev'
include/net/cfg80211.h:2056: warning: Function parameter or member 'param.band_pref' not described in 'cfg80211_bss_selection'
include/net/cfg80211.h:2056: warning: Function parameter or member 'param.adjust' not described in 'cfg80211_bss_selection'
include/net/cfg80211.h:3278: warning: Excess enum value 'WIPHY_FLAG_SUPPORTS_SCHED_SCAN' description in 'wiphy_flags'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ibss' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.connect' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.keys' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ie' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ie_len' not described in 'wireless_dev'
>> include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.bssid' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.prev_bssid' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ssid' not described in 'wireless_dev'
>> include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.default_key' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.default_mgmt_key' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.prev_bssid_valid' not described in 'wireless_dev'
include/net/cfg80211.h:2056: warning: Function parameter or member 'param.band_pref' not described in 'cfg80211_bss_selection'
include/net/cfg80211.h:2056: warning: Function parameter or member 'param.adjust' not described in 'cfg80211_bss_selection'
include/net/cfg80211.h:3278: warning: Excess enum value 'WIPHY_FLAG_SUPPORTS_SCHED_SCAN' description in 'wiphy_flags'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ibss' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.connect' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.keys' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ie' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ie_len' not described in 'wireless_dev'
>> include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.bssid' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.prev_bssid' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ssid' not described in 'wireless_dev'
>> include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.default_key' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.default_mgmt_key' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.prev_bssid_valid' not described in 'wireless_dev'
include/net/cfg80211.h:2056: warning: Function parameter or member 'param.band_pref' not described in 'cfg80211_bss_selection'
include/net/cfg80211.h:2056: warning: Function parameter or member 'param.adjust' not described in 'cfg80211_bss_selection'
include/net/cfg80211.h:3278: warning: Excess enum value 'WIPHY_FLAG_SUPPORTS_SCHED_SCAN' description in 'wiphy_flags'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ibss' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.connect' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.keys' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ie' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ie_len' not described in 'wireless_dev'
>> include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.bssid' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.prev_bssid' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ssid' not described in 'wireless_dev'
>> include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.default_key' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.default_mgmt_key' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.prev_bssid_valid' not described in 'wireless_dev'
include/net/cfg80211.h:2056: warning: Function parameter or member 'param.band_pref' not described in 'cfg80211_bss_selection'
include/net/cfg80211.h:2056: warning: Function parameter or member 'param.adjust' not described in 'cfg80211_bss_selection'
include/net/cfg80211.h:3278: warning: Excess enum value 'WIPHY_FLAG_SUPPORTS_SCHED_SCAN' description in 'wiphy_flags'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ibss' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.connect' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.keys' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ie' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ie_len' not described in 'wireless_dev'
>> include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.bssid' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.prev_bssid' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ssid' not described in 'wireless_dev'
>> include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.default_key' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.default_mgmt_key' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.prev_bssid_valid' not described in 'wireless_dev'
include/net/cfg80211.h:2056: warning: Function parameter or member 'param.band_pref' not described in 'cfg80211_bss_selection'
include/net/cfg80211.h:2056: warning: Function parameter or member 'param.adjust' not described in 'cfg80211_bss_selection'
include/net/cfg80211.h:3278: warning: Excess enum value 'WIPHY_FLAG_SUPPORTS_SCHED_SCAN' description in 'wiphy_flags'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ibss' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.connect' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.keys' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ie' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ie_len' not described in 'wireless_dev'
>> include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.bssid' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.prev_bssid' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ssid' not described in 'wireless_dev'
>> include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.default_key' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.default_mgmt_key' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.prev_bssid_valid' not described in 'wireless_dev'
include/net/cfg80211.h:2056: warning: Function parameter or member 'param.band_pref' not described in 'cfg80211_bss_selection'
include/net/cfg80211.h:2056: warning: Function parameter or member 'param.adjust' not described in 'cfg80211_bss_selection'
include/net/cfg80211.h:3278: warning: Excess enum value 'WIPHY_FLAG_SUPPORTS_SCHED_SCAN' description in 'wiphy_flags'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ibss' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.connect' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.keys' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ie' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ie_len' not described in 'wireless_dev'
>> include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.bssid' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.prev_bssid' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ssid' not described in 'wireless_dev'
>> include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.default_key' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.default_mgmt_key' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.prev_bssid_valid' not described in 'wireless_dev'
include/net/cfg80211.h:2056: warning: Function parameter or member 'param.band_pref' not described in 'cfg80211_bss_selection'
include/net/cfg80211.h:2056: warning: Function parameter or member 'param.adjust' not described in 'cfg80211_bss_selection'
include/net/cfg80211.h:3278: warning: Excess enum value 'WIPHY_FLAG_SUPPORTS_SCHED_SCAN' description in 'wiphy_flags'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ibss' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.connect' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.keys' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ie' not described in 'wireless_dev'
include/net/cfg80211.h:4115: warning: Function parameter or member 'wext.ie_len' not described in 'wireless_dev'
vim +4115 include/net/cfg80211.h
4a4b8169 Andrew Zaborowski 2017-02-10 4113
4a4b8169 Andrew Zaborowski 2017-02-10 4114 struct cfg80211_cqm_config *cqm_config;
d3236553 Johannes Berg 2009-04-20 @4115 };
d3236553 Johannes Berg 2009-04-20 4116
:::::: The code at line 4115 was first introduced by commit
:::::: d323655372590c533c275b1d798f9d1221efb5c6 cfg80211: clean up includes
:::::: TO: Johannes Berg <johannes@sipsolutions.net>
:::::: CC: John W. Linville <linville@tuxdriver.com>
---
0-DAY kernel test infrastructure Open Source Technology Center
https://lists.01.org/pipermail/kbuild-all Intel Corporation
[-- Attachment #2: .config.gz --]
[-- Type: application/gzip, Size: 6843 bytes --]
^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH v4 16/18] scripts: kernel-doc: improve nested logic to handle multiple identifiers
2017-12-18 12:30 ` [PATCH v4 16/18] scripts: kernel-doc: improve nested logic to handle multiple identifiers Mauro Carvalho Chehab
2017-12-21 9:57 ` kbuild test robot
@ 2018-02-14 16:07 ` Jani Nikula
2018-02-14 17:53 ` Mauro Carvalho Chehab
1 sibling, 1 reply; 28+ messages in thread
From: Jani Nikula @ 2018-02-14 16:07 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Linux Media Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab,
Linux Doc Mailing List, chris
On Mon, 18 Dec 2017, Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> It is possible to use nested structs like:
>
> struct {
> struct {
> void *arg1;
> } st1, st2, *st3, st4;
> };
>
> Handling it requires to split each parameter. Change the logic
> to allow such definitions.
>
> In order to test the new nested logic, the following file
> was used to test
Hi Mauro, resurrecting an old thread...
So this was a great improvement to documenting nested structs. However,
it looks like it only supports describing the nested structs at the top
level comment, and fails for inline documentation comments.
For example, in v4.16-rc1:
$ scripts/kernel-doc -none drivers/gpu/drm/i915/intel_dpio_phy.c
drivers/gpu/drm/i915/intel_dpio_phy.c:154: warning: Function parameter or member 'channel.port' not described in 'bxt_ddi_phy_info'
The struct in question is:
/**
* struct bxt_ddi_phy_info - Hold info for a broxton DDI phy
*/
struct bxt_ddi_phy_info {
/* [some members removed] */
/**
* @channel: struct containing per channel information.
*/
struct {
/**
* @port: which port maps to this channel.
*/
enum port port;
} channel[2];
};
Apparently the only way to currently do this is to add channel.port at
the top level:
/**
* struct bxt_ddi_phy_info - Hold info for a broxton DDI phy
* @channel.port: which port maps to this channel.
*/
Which is less than perfect if you have everything else described
inline. :(
BR,
Jani.
>
> <code>
> struct foo { int a; }; /* Just to avoid errors if compiled */
>
> /**
> * struct my_struct - a struct with nested unions and structs
> * @arg1: first argument of anonymous union/anonymous struct
> * @arg2: second argument of anonymous union/anonymous struct
> * @arg1b: first argument of anonymous union/anonymous struct
> * @arg2b: second argument of anonymous union/anonymous struct
> * @arg3: third argument of anonymous union/anonymous struct
> * @arg4: fourth argument of anonymous union/anonymous struct
> * @bar.st1.arg1: first argument of struct st1 on union bar
> * @bar.st1.arg2: second argument of struct st1 on union bar
> * @bar.st1.bar1: bar1 at st1
> * @bar.st1.bar2: bar2 at st1
> * @bar.st2.arg1: first argument of struct st2 on union bar
> * @bar.st2.arg2: second argument of struct st2 on union bar
> * @bar.st3.arg2: second argument of struct st3 on union bar
> * @f1: nested function on anonimous union/struct
> * @bar.st2.f2: nested function on named union/struct
> */
> struct my_struct {
> /* Anonymous union/struct*/
> union {
> struct {
> char arg1 : 1;
> char arg2 : 3;
> };
> struct {
> int arg1b;
> int arg2b;
> };
> struct {
> void *arg3;
> int arg4;
> int (*f1)(char foo, int bar);
> };
> };
> union {
> struct {
> int arg1;
> int arg2;
> struct foo bar1, *bar2;
> } st1; /* bar.st1 is undocumented, cause a warning */
> struct {
> void *arg1; /* bar.st3.arg1 is undocumented, cause a warning */
> int arg2;
> int (*f2)(char foo, int bar); /* bar.st3.fn2 is undocumented, cause a warning */
> } st2, st3, *st4;
> int (*f3)(char foo, int bar); /* f3 is undocumented, cause a warning */
> } bar; /* bar is undocumented, cause a warning */
>
> /* private: */
> int undoc_privat; /* is undocumented but private, no warning */
>
> /* public: */
> int undoc_public; /* is undocumented, cause a warning */
> };
> </code>
>
> It produces the following warnings, as expected:
>
> test2.h:57: warning: Function parameter or member 'bar' not described in 'my_struct'
> test2.h:57: warning: Function parameter or member 'bar.st1' not described in 'my_struct'
> test2.h:57: warning: Function parameter or member 'bar.st2' not described in 'my_struct'
> test2.h:57: warning: Function parameter or member 'bar.st3' not described in 'my_struct'
> test2.h:57: warning: Function parameter or member 'bar.st3.arg1' not described in 'my_struct'
> test2.h:57: warning: Function parameter or member 'bar.st3.f2' not described in 'my_struct'
> test2.h:57: warning: Function parameter or member 'bar.st4' not described in 'my_struct'
> test2.h:57: warning: Function parameter or member 'bar.st4.arg1' not described in 'my_struct'
> test2.h:57: warning: Function parameter or member 'bar.st4.arg2' not described in 'my_struct'
> test2.h:57: warning: Function parameter or member 'bar.st4.f2' not described in 'my_struct'
> test2.h:57: warning: Function parameter or member 'bar.f3' not described in 'my_struct'
> test2.h:57: warning: Function parameter or member 'undoc_public' not described in 'my_struct'
>
> Suggested-by: Markus Heiser <markus.heiser@darmarit.de>
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
> scripts/kernel-doc | 69 ++++++++++++++++++++++++++++++++++--------------------
> 1 file changed, 44 insertions(+), 25 deletions(-)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 5d03c9086323..0bda21d9d3f2 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -1030,15 +1030,16 @@ sub dump_struct($$) {
> my $declaration = $members;
>
> # Split nested struct/union elements as newer ones
> - my $cont = 1;
> - while ($cont) {
> - $cont = 0;
> - while ($members =~ m/(struct|union)([^{};]+){([^{}]*)}([^{}\;]*)\;/) {
> - my $newmember = "$1 $4;";
> - my $id = $4;
> - my $content = $3;
> + while ($members =~ m/(struct|union)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;/) {
> + my $newmember;
> + my $maintype = $1;
> + my $ids = $4;
> + my $content = $3;
> + foreach my $id(split /,/, $ids) {
> + $newmember .= "$maintype $id; ";
> +
> $id =~ s/[:\[].*//;
> - $id =~ s/^\*+//;
> + $id =~ s/^\s*\**(\S+)\s*/$1/;
> foreach my $arg (split /;/, $content) {
> next if ($arg =~ m/^\s*$/);
> if ($arg =~ m/^([^\(]+\(\*?\s*)([\w\.]*)(\s*\).*)/) {
> @@ -1049,30 +1050,48 @@ sub dump_struct($$) {
> next if (!$name);
> if ($id =~ m/^\s*$/) {
> # anonymous struct/union
> - $newmember .= "$type$name$extra;";
> + $newmember .= "$type$name$extra; ";
> } else {
> - $newmember .= "$type$id.$name$extra;";
> + $newmember .= "$type$id.$name$extra; ";
> }
> } else {
> - my $type = $arg;
> - my $name = $arg;
> - $type =~ s/\s\S+$//;
> - $name =~ s/.*\s+//;
> - $name =~ s/[:\[].*//;
> - $name =~ s/^\*+//;
> - next if (($name =~ m/^\s*$/));
> - if ($id =~ m/^\s*$/) {
> - # anonymous struct/union
> - $newmember .= "$type $name;";
> + my $type;
> + my $names;
> + $arg =~ s/^\s+//;
> + $arg =~ s/\s+$//;
> + # Handle bitmaps
> + $arg =~ s/:\s*\d+\s*//g;
> + # Handle arrays
> + $arg =~ s/\[\S+\]//g;
> + # The type may have multiple words,
> + # and multiple IDs can be defined, like:
> + # const struct foo, *bar, foobar
> + # So, we remove spaces when parsing the
> + # names, in order to match just names
> + # and commas for the names
> + $arg =~ s/\s*,\s*/,/g;
> + if ($arg =~ m/(.*)\s+([\S+,]+)/) {
> + $type = $1;
> + $names = $2;
> } else {
> - $newmember .= "$type $id.$name;";
> + $newmember .= "$arg; ";
> + next;
> + }
> + foreach my $name (split /,/, $names) {
> + $name =~ s/^\s*\**(\S+)\s*/$1/;
> + next if (($name =~ m/^\s*$/));
> + if ($id =~ m/^\s*$/) {
> + # anonymous struct/union
> + $newmember .= "$type $name; ";
> + } else {
> + $newmember .= "$type $id.$name; ";
> + }
> }
> }
> }
> - $members =~ s/(struct|union)([^{};]+){([^{}]*)}([^{}\;]*)\;/$newmember/;
> - $cont = 1;
> - };
> - };
> + }
> + $members =~ s/(struct|union)([^\{\};]+)\{([^\{\}]*)}([^\{\}\;]*)\;/$newmember/;
> + }
>
> # Ignore other nested elements, like enums
> $members =~ s/({[^\{\}]*})//g;
--
Jani Nikula, Intel Open Source Technology Center
^ permalink raw reply [flat|nested] 28+ messages in thread* Re: [PATCH v4 16/18] scripts: kernel-doc: improve nested logic to handle multiple identifiers
2018-02-14 16:07 ` Jani Nikula
@ 2018-02-14 17:53 ` Mauro Carvalho Chehab
2018-02-14 18:20 ` Jani Nikula
0 siblings, 1 reply; 28+ messages in thread
From: Mauro Carvalho Chehab @ 2018-02-14 17:53 UTC (permalink / raw)
To: Jani Nikula
Cc: Linux Media Mailing List, Jonathan Corbet, Mauro Carvalho Chehab,
Linux Doc Mailing List, chris
Em Wed, 14 Feb 2018 18:07:03 +0200
Jani Nikula <jani.nikula@linux.intel.com> escreveu:
> On Mon, 18 Dec 2017, Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> > It is possible to use nested structs like:
> >
> > struct {
> > struct {
> > void *arg1;
> > } st1, st2, *st3, st4;
> > };
> >
> > Handling it requires to split each parameter. Change the logic
> > to allow such definitions.
> >
> > In order to test the new nested logic, the following file
> > was used to test
>
> Hi Mauro, resurrecting an old thread...
>
> So this was a great improvement to documenting nested structs. However,
> it looks like it only supports describing the nested structs at the top
> level comment, and fails for inline documentation comments.
True. I didn't consider inline comments when I wrote the patch.
We don't use inline doc tags at media. IMO, a single description block
on the top works better, but yeah, it would be very good if it would
support nested structs to also have inlined comments.
Yet, on a quick hack:
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index fee8952037b1..e2d5cadd8d0b 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1009,6 +1009,8 @@ sub dump_struct($$) {
$declaration_name = $2;
my $members = $3;
+print "members: $members\n";
+
# ignore members marked private:
$members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
$members =~ s/\/\*\s*private:.*//gosi;
produce:
$ scripts/kernel-doc -none drivers/gpu/drm/i915/intel_dpio_phy.c
members: bool dual_channel; enum dpio_phy rcomp_phy; int reset_delay; u32 pwron_mask; struct { enum port port; } channel[2];
drivers/gpu/drm/i915/intel_dpio_phy.c:154: warning: Function parameter or member 'channel.port' not described in 'bxt_ddi_phy_info'
So, dump_struct() already receives the struct sanitizes without any comments
inside.
There is a simple fix, though. Make inline comments to accept a dot:
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index fee8952037b1..06d7f3f2c094 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -363,7 +363,7 @@ my $doc_sect = $doc_com .
my $doc_content = $doc_com_body . '(.*)';
my $doc_block = $doc_com . 'DOC:\s*(.*)?';
my $doc_inline_start = '^\s*/\*\*\s*$';
-my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
+my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';
my $doc_inline_end = '^\s*\*/\s*$';
my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
That requires a small change at the inline parameters, though:
diff --git a/drivers/gpu/drm/i915/intel_dpio_phy.c b/drivers/gpu/drm/i915/intel_dpio_phy.c
index 76473e9836c6..c8e9e44e5981 100644
--- a/drivers/gpu/drm/i915/intel_dpio_phy.c
+++ b/drivers/gpu/drm/i915/intel_dpio_phy.c
@@ -147,7 +147,7 @@ struct bxt_ddi_phy_info {
*/
struct {
/**
- * @port: which port maps to this channel.
+ * @channel.port: which port maps to this channel.
*/
enum port port;
} channel[2];
The alternative would be a way more complex: to teach the code with
starts at:
If ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
About how to handle with inlined structs/enums at inlined comments.
Thanks,
Mauro
^ permalink raw reply related [flat|nested] 28+ messages in thread* Re: [PATCH v4 16/18] scripts: kernel-doc: improve nested logic to handle multiple identifiers
2018-02-14 17:53 ` Mauro Carvalho Chehab
@ 2018-02-14 18:20 ` Jani Nikula
2018-02-16 14:09 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 28+ messages in thread
From: Jani Nikula @ 2018-02-14 18:20 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Media Mailing List, Jonathan Corbet, Mauro Carvalho Chehab,
Linux Doc Mailing List, chris
On Wed, 14 Feb 2018, Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> There is a simple fix, though. Make inline comments to accept a dot:
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index fee8952037b1..06d7f3f2c094 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -363,7 +363,7 @@ my $doc_sect = $doc_com .
> my $doc_content = $doc_com_body . '(.*)';
> my $doc_block = $doc_com . 'DOC:\s*(.*)?';
> my $doc_inline_start = '^\s*/\*\*\s*$';
> -my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
> +my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';
> my $doc_inline_end = '^\s*\*/\s*$';
> my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
> my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
>
> That requires a small change at the inline parameters, though:
>
> diff --git a/drivers/gpu/drm/i915/intel_dpio_phy.c b/drivers/gpu/drm/i915/intel_dpio_phy.c
> index 76473e9836c6..c8e9e44e5981 100644
> --- a/drivers/gpu/drm/i915/intel_dpio_phy.c
> +++ b/drivers/gpu/drm/i915/intel_dpio_phy.c
> @@ -147,7 +147,7 @@ struct bxt_ddi_phy_info {
> */
> struct {
> /**
> - * @port: which port maps to this channel.
> + * @channel.port: which port maps to this channel.
> */
> enum port port;
> } channel[2];
Perhaps it would be slightly more elegant to be able to leave out
"channel." here and deduce that from the context... but the above
matches what you'd write in the higher level struct comment, and
produces the same output. It works and it's really simple. I like it.
Please submit this as a proper patch, with
Tested-by: Jani Nikula <jani.nikula@intel.com>
BR,
Jani.
--
Jani Nikula, Intel Open Source Technology Center
^ permalink raw reply [flat|nested] 28+ messages in thread* Re: [PATCH v4 16/18] scripts: kernel-doc: improve nested logic to handle multiple identifiers
2018-02-14 18:20 ` Jani Nikula
@ 2018-02-16 14:09 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 28+ messages in thread
From: Mauro Carvalho Chehab @ 2018-02-16 14:09 UTC (permalink / raw)
To: Jani Nikula
Cc: Linux Media Mailing List, Jonathan Corbet, Mauro Carvalho Chehab,
Linux Doc Mailing List, chris
Em Wed, 14 Feb 2018 20:20:21 +0200
Jani Nikula <jani.nikula@linux.intel.com> escreveu:
> On Wed, 14 Feb 2018, Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> > There is a simple fix, though. Make inline comments to accept a dot:
> >
> > diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> > index fee8952037b1..06d7f3f2c094 100755
> > --- a/scripts/kernel-doc
> > +++ b/scripts/kernel-doc
> > @@ -363,7 +363,7 @@ my $doc_sect = $doc_com .
> > my $doc_content = $doc_com_body . '(.*)';
> > my $doc_block = $doc_com . 'DOC:\s*(.*)?';
> > my $doc_inline_start = '^\s*/\*\*\s*$';
> > -my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
> > +my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';
> > my $doc_inline_end = '^\s*\*/\s*$';
> > my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
> > my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
> >
> > That requires a small change at the inline parameters, though:
> >
> > diff --git a/drivers/gpu/drm/i915/intel_dpio_phy.c b/drivers/gpu/drm/i915/intel_dpio_phy.c
> > index 76473e9836c6..c8e9e44e5981 100644
> > --- a/drivers/gpu/drm/i915/intel_dpio_phy.c
> > +++ b/drivers/gpu/drm/i915/intel_dpio_phy.c
> > @@ -147,7 +147,7 @@ struct bxt_ddi_phy_info {
> > */
> > struct {
> > /**
> > - * @port: which port maps to this channel.
> > + * @channel.port: which port maps to this channel.
> > */
> > enum port port;
> > } channel[2];
>
> Perhaps it would be slightly more elegant to be able to leave out
> "channel." here and deduce that from the context... but the above
> matches what you'd write in the higher level struct comment, and
> produces the same output. It works and it's really simple. I like it.
>
> Please submit this as a proper patch, with
>
> Tested-by: Jani Nikula <jani.nikula@intel.com>
Submitted. I ended by submitting as a patch series, as, when I
did some tests with the examples, I found that kernel-doc have
issues parsing them.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 28+ messages in thread
* [PATCH v4 17/18] scripts: kernel-doc: apply filtering rules to warnings
2017-12-18 12:30 [PATCH v4 00/18] kernel-doc: add supported to document nested structs Mauro Carvalho Chehab
` (15 preceding siblings ...)
2017-12-18 12:30 ` [PATCH v4 16/18] scripts: kernel-doc: improve nested logic to handle multiple identifiers Mauro Carvalho Chehab
@ 2017-12-18 12:30 ` Mauro Carvalho Chehab
2017-12-18 12:30 ` [PATCH v4 18/18] w1_netlink.h: add support for nested structs Mauro Carvalho Chehab
2017-12-21 21:08 ` [PATCH v4 00/18] kernel-doc: add supported to document " Jonathan Corbet
18 siblings, 0 replies; 28+ messages in thread
From: Mauro Carvalho Chehab @ 2017-12-18 12:30 UTC (permalink / raw)
To: Linux Media Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Linux Doc Mailing List
When kernel-doc is called with output selection filters,
it will be called lots of time for a single file. If
there is a warning present there, it means that it may
print hundreds of identical warnings.
Worse than that, the -function NAME actually filters only
functions. So, it makes no sense at all to print warnings
for structs or enums.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
scripts/kernel-doc | 30 +++++++++++++++++++++++-------
1 file changed, 23 insertions(+), 7 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 0bda21d9d3f2..1e2b35ce1c9d 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1160,16 +1160,26 @@ sub dump_enum($$) {
push @parameterlist, $arg;
if (!$parameterdescs{$arg}) {
$parameterdescs{$arg} = $undescribed;
- print STDERR "${file}:$.: warning: Enum value '$arg' ".
- "not described in enum '$declaration_name'\n";
+ if (($output_selection == OUTPUT_ALL) ||
+ ($output_selection == OUTPUT_INCLUDE &&
+ defined($function_table{$declaration_name})) ||
+ ($output_selection == OUTPUT_EXCLUDE &&
+ !defined($function_table{$declaration_name}))) {
+ print STDERR "${file}:$.: warning: Enum value '$arg' not described in enum '$declaration_name'\n";
+ }
}
$_members{$arg} = 1;
}
while (my ($k, $v) = each %parameterdescs) {
if (!exists($_members{$k})) {
- print STDERR "${file}:$.: warning: Excess enum value " .
- "'$k' description in '$declaration_name'\n";
+ if (($output_selection == OUTPUT_ALL) ||
+ ($output_selection == OUTPUT_INCLUDE &&
+ defined($function_table{$declaration_name})) ||
+ ($output_selection == OUTPUT_EXCLUDE &&
+ !defined($function_table{$declaration_name}))) {
+ print STDERR "${file}:$.: warning: Excess enum value '$k' description in '$declaration_name'\n";
+ }
}
}
@@ -1375,9 +1385,15 @@ sub push_parameter($$$$) {
if (!defined $parameterdescs{$param} && $param !~ /^#/) {
$parameterdescs{$param} = $undescribed;
- print STDERR
- "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n";
- ++$warnings;
+ if (($output_selection == OUTPUT_ALL) ||
+ ($output_selection == OUTPUT_INCLUDE &&
+ defined($function_table{$declaration_name})) ||
+ ($output_selection == OUTPUT_EXCLUDE &&
+ !defined($function_table{$declaration_name}))) {
+ print STDERR
+ "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n";
+ ++$warnings;
+ }
}
$param = xml_escape($param);
--
2.14.3
^ permalink raw reply related [flat|nested] 28+ messages in thread* [PATCH v4 18/18] w1_netlink.h: add support for nested structs
2017-12-18 12:30 [PATCH v4 00/18] kernel-doc: add supported to document nested structs Mauro Carvalho Chehab
` (16 preceding siblings ...)
2017-12-18 12:30 ` [PATCH v4 17/18] scripts: kernel-doc: apply filtering rules to warnings Mauro Carvalho Chehab
@ 2017-12-18 12:30 ` Mauro Carvalho Chehab
2017-12-21 21:08 ` [PATCH v4 00/18] kernel-doc: add supported to document " Jonathan Corbet
18 siblings, 0 replies; 28+ messages in thread
From: Mauro Carvalho Chehab @ 2017-12-18 12:30 UTC (permalink / raw)
To: Linux Media Mailing List, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab,
Linux Doc Mailing List, Evgeniy Polyakov
Now that kernel-doc can hanle nested structs/unions, describe
such fields at w1_netlink_message_types.
Acked-by: Evgeniy Polyakov <zbr@ioremap.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
drivers/w1/w1_netlink.h | 6 +++++-
1 file changed, 5 insertions(+), 1 deletion(-)
diff --git a/drivers/w1/w1_netlink.h b/drivers/w1/w1_netlink.h
index a36661cd1f05..f876772c0fb4 100644
--- a/drivers/w1/w1_netlink.h
+++ b/drivers/w1/w1_netlink.h
@@ -59,7 +59,11 @@ enum w1_netlink_message_types {
* @type: one of enum w1_netlink_message_types
* @status: kernel feedback for success 0 or errno failure value
* @len: length of data following w1_netlink_msg
- * @id: union holding master bus id (msg.id) and slave device id (id[8]).
+ * @id: union holding bus master id (msg.id) and slave device id (id[8]).
+ * @id.id: Slave ID (8 bytes)
+ * @id.mst: bus master identification
+ * @id.mst.id: bus master ID
+ * @id.mst.res: bus master reserved
* @data: start address of any following data
*
* The base message structure for w1 messages over netlink.
--
2.14.3
^ permalink raw reply related [flat|nested] 28+ messages in thread* Re: [PATCH v4 00/18] kernel-doc: add supported to document nested structs
2017-12-18 12:30 [PATCH v4 00/18] kernel-doc: add supported to document nested structs Mauro Carvalho Chehab
` (17 preceding siblings ...)
2017-12-18 12:30 ` [PATCH v4 18/18] w1_netlink.h: add support for nested structs Mauro Carvalho Chehab
@ 2017-12-21 21:08 ` Jonathan Corbet
2017-12-21 21:35 ` Mauro Carvalho Chehab
18 siblings, 1 reply; 28+ messages in thread
From: Jonathan Corbet @ 2017-12-21 21:08 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Media Mailing List, Mauro Carvalho Chehab, Linux Doc Mailing List
On Mon, 18 Dec 2017 10:30:01 -0200
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> This is a rebased version of my patch series that add support for
> nested structs on kernel-doc. With this version, it won't produce anymore
> hundreds of identical warnings, as patch 17 removes the warning
> duplication.
>
> Excluding warnings about duplicated Note: section at hash.h, before
> this series, it reports 166 kernel-doc warnings. After this patch series,
> it reports 123 kernel-doc warnings, being 51 from DVB. I have already a patch
> series that will cleanup those new DVB warnings due to nested structs.
>
> So, the net result is that the number of warnings is reduced with
> this version.
This seems like a great set of improvements overall, and I love getting
rid of all that old kernel-doc code. I will note that it makes a full
htmldocs build take 20-30 seconds longer, which is not entirely
welcome, but so be it. Someday, I guess, $SOMEBODY should see if there's
some low-hanging optimization fruit there.
Applied, thanks.
jon
^ permalink raw reply [flat|nested] 28+ messages in thread* Re: [PATCH v4 00/18] kernel-doc: add supported to document nested structs
2017-12-21 21:08 ` [PATCH v4 00/18] kernel-doc: add supported to document " Jonathan Corbet
@ 2017-12-21 21:35 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 28+ messages in thread
From: Mauro Carvalho Chehab @ 2017-12-21 21:35 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Linux Media Mailing List, Mauro Carvalho Chehab, Linux Doc Mailing List
Em Thu, 21 Dec 2017 14:08:43 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:
> On Mon, 18 Dec 2017 10:30:01 -0200
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
>
> > This is a rebased version of my patch series that add support for
> > nested structs on kernel-doc. With this version, it won't produce anymore
> > hundreds of identical warnings, as patch 17 removes the warning
> > duplication.
> >
> > Excluding warnings about duplicated Note: section at hash.h, before
> > this series, it reports 166 kernel-doc warnings. After this patch series,
> > it reports 123 kernel-doc warnings, being 51 from DVB. I have already a patch
> > series that will cleanup those new DVB warnings due to nested structs.
> >
> > So, the net result is that the number of warnings is reduced with
> > this version.
>
> This seems like a great set of improvements overall, and I love getting
> rid of all that old kernel-doc code.
> I will note that it makes a full
> htmldocs build take 20-30 seconds longer, which is not entirely
> welcome, but so be it. Someday, I guess, $SOMEBODY should see if there's
> some low-hanging optimization fruit there.
Yeah. Well, I used a recursive algorithm, with can be painfull if there
are mang things to parse.
Anyway, I didn't notice it, because there was a major performance regression
that happened recently that it is affecting all my sphinx builds: trying to
compile stuff in parallel with SPHINXOPTS=-j5 is crashing with:
# Loaded extensions:
# kfigure (1.0.0) from /devel/v4l/patchwork/Documentation/sphinx/kfigure.py
# kernel_include (1.0) from /devel/v4l/patchwork/Documentation/sphinx/kernel_include.py
# rstFlatTable (1.0) from /devel/v4l/patchwork/Documentation/sphinx/rstFlatTable.py
# cdomain (1.0) from /devel/v4l/patchwork/Documentation/sphinx/cdomain.py
# kerneldoc (1.0) from /devel/v4l/patchwork/Documentation/sphinx/kerneldoc.py
# alabaster (0.7.10) from /devel/v4l/docs/sphinx_1.4/lib/python2.7/site-packages/alabaster/__init__.pyc
# sphinx.ext.imgmath (1.4.9) from /devel/v4l/docs/sphinx_1.4/lib/python2.7/site-packages/sphinx/ext/imgmath.pyc
Traceback (most recent call last):
File "/devel/v4l/docs/sphinx_1.4/lib/python2.7/site-packages/sphinx/cmdline.py", line 244, in main
app.build(opts.force_all, filenames)
File "/devel/v4l/docs/sphinx_1.4/lib/python2.7/site-packages/sphinx/application.py", line 297, in build
self.builder.build_update()
File "/devel/v4l/docs/sphinx_1.4/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 251, in build_update
'out of date' % len(to_build))
File "/devel/v4l/docs/sphinx_1.4/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 265, in build
self.doctreedir, self.app))
File "/devel/v4l/docs/sphinx_1.4/lib/python2.7/site-packages/sphinx/environment.py", line 567, in update
self._read_parallel(docnames, app, nproc=app.parallel)
File "/devel/v4l/docs/sphinx_1.4/lib/python2.7/site-packages/sphinx/environment.py", line 625, in _read_parallel
tasks.join()
File "/devel/v4l/docs/sphinx_1.4/lib/python2.7/site-packages/sphinx/util/parallel.py", line 92, in join
self._join_one()
File "/devel/v4l/docs/sphinx_1.4/lib/python2.7/site-packages/sphinx/util/parallel.py", line 97, in _join_one
exc, result = pipe.recv()
EOFError
I had to change my build scripts to remove parallel build, with increased
*a lot* the building time. So, right now, I just go out to take a coffee
or two when building documentation, as, without -j (even without this
patch series), is really slow.
If someone wants to look into it, the breakage happened by the time
I upgraded to Fedora 27 and Kernel 4.14 was released. Yet, I'm using
pip for Sphinx.
So, I dunno what's the culprit. I didn't have time yet to investigate.
> Applied, thanks.
Thank you!
Regards,
Mauro
^ permalink raw reply [flat|nested] 28+ messages in thread