diff options
author | Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> | 2015-08-04 09:04:08 -0300 |
---|---|---|
committer | Jonathan Corbet <corbet@lwn.net> | 2015-08-06 13:05:35 -0600 |
commit | a4c6ebede2f99fc3aaa5a42228a16747d0aa2504 (patch) | |
tree | 14b2121cd22d9e58e10ec07c05d963740142aeb1 | |
parent | 64e32895f9d87aaa0842c07d0b17f4895955db20 (diff) |
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>
-rwxr-xr-x | scripts/kernel-doc | 77 |
1 files changed, 75 insertions, 2 deletions
diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 0ac1a07874cc..3a4d895b9237 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 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); |