Re: [PATCH] scripts/kernel-doc Allow struct arguments documentation in struct body

On 08/03/2015 12:59 PM, Randy Dunlap wrote:

On 07/31/15 14:06, Danilo Cesar Lemes de Paula wrote:

...

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

---

scripts/kernel-doc | 80 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 78 insertions(+), 2 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 9922e66..9bfa8b9 100755 --- 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 for arguments only.

                used

What are "arguments" in this context? do you mean struct fields or members?

Yes. I can change the text if you want to.

...

+# # 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 @@ -287,9 +311,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; @@ -304,6 +338,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; @@ -2181,6 +2218,7 @@ sub reset_state { $prototype = "";

 $state = 0;

• $split_doc_state = 0;

}

sub tracepoint_munge($) { @@ -2453,7 +2491,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;

@@ -2494,8 +2531,47 @@ 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;
  

•    # End commend */
  

         comment

Fixed in my next v2.

Thanks

...

•    } 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;