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>
This commit is contained in:
Danilo Cesar Lemes de Paula
Jonathan Corbet
parent
64e32895f9
commit
a4c6ebede2
|
|
@ -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);
|
||||
|
|
|
|||
Loading…
Reference in New Issue