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

[Randy Dunlap <rdunlap@infradead.org>]

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?

> +#
>  # 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

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

-- 
~Randy