Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1755641AbbHDJEW (ORCPT ); Tue, 4 Aug 2015 05:04:22 -0400 Received: from mail-wi0-f179.google.com ([209.85.212.179]:35681 "EHLO mail-wi0-f179.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1755551AbbHDJER (ORCPT ); Tue, 4 Aug 2015 05:04:17 -0400 Date: Tue, 4 Aug 2015 11:04:13 +0200 From: Daniel Vetter To: Danilo Cesar Lemes de Paula Cc: linux-doc@vger.kernel.org, Randy Dunlap , Daniel Vetter , Laurent Pinchart , Jonathan Corbet , Herbert Xu , Stephan Mueller , Michal Marek , linux-kernel@vger.kernel.org, intel-gfx , dri-devel Subject: Re: [PATCH] scripts/kernel-doc Allow struct arguments documentation in struct body Message-ID: <20150804090412.GG24689@phenom.ffwll.local> Mail-Followup-To: Danilo Cesar Lemes de Paula , linux-doc@vger.kernel.org, Randy Dunlap , Laurent Pinchart , Jonathan Corbet , Herbert Xu , Stephan Mueller , Michal Marek , linux-kernel@vger.kernel.org, intel-gfx , dri-devel References: <1438376805-8964-1-git-send-email-danilo.cesar@collabora.co.uk> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <1438376805-8964-1-git-send-email-danilo.cesar@collabora.co.uk> X-Operating-System: Linux phenom 4.2.0-rc1+ User-Agent: Mutt/1.5.23 (2014-03-12) Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 6527 Lines: 196 On Fri, Jul 31, 2015 at 06:06:45PM -0300, 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 > Cc: Randy Dunlap > Cc: Daniel Vetter > Cc: Laurent Pinchart > Cc: Jonathan Corbet > Cc: Herbert Xu > Cc: Stephan Mueller > Cc: Michal Marek > Cc: linux-kernel@vger.kernel.org > Cc: linux-doc@vger.kernel.org > Cc: intel-gfx > Cc: dri-devel > --- > 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. > +# > # 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; You're using a mix of tabs and spaces here to indent. Ofc we need 4 spaces for odd indent levels, but for others it shouldn't be required. -Daniel > + 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 */ > + } 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); > -- > 2.4.6 > -- Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/