scripts/kernel-doc Allow struct arguments documentation in struct body

Describing arguments at top of a struct definition works fine
for small/medium size structs, but it definitely doesn't work well
for struct with a huge list of elements.

Keeping the arguments list inside the struct body makes it easier
to maintain the documentation.
ie:
/**
 * struct my_struct - short description
 * @a: first member
 * @b: second member
 *
 * Longer description
 */
struct my_struct {
    int a;
    int b;
    /**
     * @c: This is longer description of C
     *
     * You can use paragraphs to describe arguments
     * using this method.
     */
    int c;
};

This patch allows the use of this kind of syntax. Only one argument
per comment and user can use how many paragraphs he needs. It should
start with /**, which is already being used by kernel-doc. If those
comment doesn't follow those rules, it will be ignored.

Signed-off-by: Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk>
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Herbert Xu <herbert@gondor.apana.org.au>
Cc: Stephan Mueller <smueller@chronox.de>
Cc: Michal Marek <mmarek@suse.cz>
Cc: linux-kernel@vger.kernel.org
Cc: linux-doc@vger.kernel.org
Cc: intel-gfx <intel-gfx@lists.freedesktop.org>
Cc: dri-devel <dri-devel@lists.freedesktop.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 0ac1a07874cc7bfe5e6677f3976e608ff6195559..3a4d895b92371da2db28d208ebaf42efbed199b8 100755 (executable)
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -133,6 +133,30 @@ use strict;
 #
 # All descriptions can be multiline, except the short function description.
 #
+# For really longs structs, you can also describe arguments inside the
+# body of the struct.
+# eg.
+# /**
+#  * struct my_struct - short description
+#  * @a: first member
+#  * @b: second member
+#  *
+#  * Longer description
+#  */
+# struct my_struct {
+#     int a;
+#     int b;
+#     /**
+#      * @c: This is longer description of C
+#      *
+#      * You can use paragraphs to describe arguments
+#      * using this method.
+#      */
+#     int c;
+# };
+#
+# This should be use only for struct/enum members.
+#
 # You can also add additional sections. When documenting kernel functions you
 # should document the "Context:" of the function, e.g. whether the functions
 # can be called form interrupts. Unlike other sections you can end it with an
@@ -296,9 +320,19 @@ my $lineprefix="";
 # 2 - scanning field start.
 # 3 - scanning prototype.
 # 4 - documentation block
+# 5 - gathering documentation outside main block
 my $state;
 my $in_doc_sect;
 
+# Split Doc State
+# 0 - Invalid (Before start or after finish)
+# 1 - Is started (the /** was found inside a struct)
+# 2 - The @parameter header was found, start accepting multi paragraph text.
+# 3 - Finished (the */ was found)
+# 4 - Error - Comment without header was found. Spit a warning as it's not
+#     proper kernel-doc and ignore the rest.
+my $split_doc_state;
+
 #declaration types: can be
 # 'function', 'struct', 'union', 'enum', 'typedef'
 my $decl_type;
@@ -313,6 +347,9 @@ my $doc_decl = $doc_com . '(\w+)';
 my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
 my $doc_content = $doc_com_body . '(.*)';
 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
+my $doc_split_start = '^\s*/\*\*\s*$';
+my $doc_split_sect = '\s*\*\s*(@[\w\s]+):(.*)';
+my $doc_split_end = '^\s*\*/\s*$';
 
 my %constants;
 my %parameterdescs;
@@ -2190,6 +2227,7 @@ sub reset_state {
     $prototype = "";
 
     $state = 0;
+    $split_doc_state = 0;
 }
 
 sub tracepoint_munge($) {
@@ -2462,7 +2500,6 @@ sub process_file($) {
                }
                $section = $newsection;
            } elsif (/$doc_end/) {
-
                if (($contents ne "") && ($contents ne "\n")) {
                    dump_section($file, $section, xml_escape($contents));
                    $section = $section_default;
@@ -2503,8 +2540,44 @@ sub process_file($) {
                print STDERR "Warning(${file}:$.): bad line: $_";
                ++$warnings;
            }
+       } elsif ($state == 5) { # scanning for split parameters
+           # First line (state 1) needs to be a @parameter
+           if ($split_doc_state == 1 && /$doc_split_sect/o) {
+               $section = $1;
+               $contents = $2;
+               if ($contents ne "") {
+                   while ((substr($contents, 0, 1) eq " ") ||
+                          substr($contents, 0, 1) eq "\t") {
+                       $contents = substr($contents, 1);
+                   }
+               $contents .= "\n";
+               }
+               $split_doc_state = 2;
+           # Documentation block end */
+           } elsif (/$doc_split_end/) {
+               if (($contents ne "") && ($contents ne "\n")) {
+                   dump_section($file, $section, xml_escape($contents));
+                   $section = $section_default;
+                   $contents = "";
+               }
+               $state = 3;
+               $split_doc_state = 0;
+           # Regular text
+           } elsif (/$doc_content/) {
+               if ($split_doc_state == 2) {
+                   $contents .= $1 . "\n";
+               } elsif ($split_doc_state == 1) {
+                   $split_doc_state = 4;
+                   print STDERR "Warning(${file}:$.): ";
+                   print STDERR "Incorrect use of kernel-doc format: $_";
+                   ++$warnings;
+               }
+           }
        } elsif ($state == 3) { # scanning for function '{' (end of prototype)
-           if ($decl_type eq 'function') {
+           if (/$doc_split_start/) {
+               $state = 5;
+               $split_doc_state = 1;
+           } elsif ($decl_type eq 'function') {
                process_state3_function($_, $file);
            } else {
                process_state3_type($_, $file);