Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1754485AbbHCP7G (ORCPT ); Mon, 3 Aug 2015 11:59:06 -0400 Received: from bombadil.infradead.org ([198.137.202.9]:59338 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753402AbbHCP7D (ORCPT ); Mon, 3 Aug 2015 11:59:03 -0400 Message-ID: <55BF8FC4.1030202@infradead.org> Date: Mon, 03 Aug 2015 08:59:00 -0700 From: Randy Dunlap User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:31.0) Gecko/20100101 Thunderbird/31.3.0 MIME-Version: 1.0 To: Danilo Cesar Lemes de Paula , linux-doc@vger.kernel.org CC: 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 References: <1438376805-8964-1-git-send-email-danilo.cesar@collabora.co.uk> In-Reply-To: <1438376805-8964-1-git-send-email-danilo.cesar@collabora.co.uk> Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: 7bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 5673 Lines: 174 On 07/31/15 14:06, 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. used What are "arguments" in this context? do you mean struct fields or 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,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; > + 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 */ comment > + } 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; > + -- ~Randy -- 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/