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 --- Changelog: v2: - Fixed comment typo - Fixed identantion by following the rest of the kernel-doc script pattern. - Improved usage comment.
scripts/kernel-doc | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 75 insertions(+), 2 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 9922e66..5adc7ee 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 @@ -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,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);