Commit a4c6ebed authored by Danilo Cesar Lemes de Paula's avatar Danilo Cesar Lemes de Paula Committed by Jonathan Corbet
Browse files

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: default avatarDanilo 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: default avatarJonathan Corbet <corbet@lwn.net>
parent 64e32895

scripts/kernel-doc

+75 −2
Original line number Diff line number Diff line
@@ -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);

CRA Git | Maintained and supported by SUSTech CRA and CCSE