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

[Danilo Cesar Lemes de Paula]

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 at collabora.co.uk>
>> Cc: Randy Dunlap <rdunlap at infradead.org>
>> Cc: Daniel Vetter <daniel.vetter at ffwll.ch>
>> Cc: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
>> Cc: Jonathan Corbet <corbet at lwn.net>
>> Cc: Herbert Xu <herbert at gondor.apana.org.au>
>> Cc: Stephan Mueller <smueller at chronox.de>
>> Cc: Michal Marek <mmarek at suse.cz>
>> Cc: linux-kernel at vger.kernel.org
>> Cc: linux-doc at vger.kernel.org
>> Cc: intel-gfx <intel-gfx at lists.freedesktop.org>
>> Cc: dri-devel <dri-devel at 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;
>> +
>