Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753932AbbHCQ3x (ORCPT ); Mon, 3 Aug 2015 12:29:53 -0400 Received: from bhuna.collabora.co.uk ([93.93.135.160]:38916 "EHLO bhuna.collabora.co.uk" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752054AbbHCQ3v (ORCPT ); Mon, 3 Aug 2015 12:29:51 -0400 Message-ID: <55BF96F6.5000600@collabora.co.uk> Date: Mon, 03 Aug 2015 13:29:42 -0300 From: Danilo Cesar Lemes de Paula User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:31.0) Gecko/20100101 Icedove/31.7.0 MIME-Version: 1.0 To: Randy Dunlap , 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> <55BF8FC4.1030202@infradead.org> In-Reply-To: <55BF8FC4.1030202@infradead.org> 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: 5957 Lines: 183 On 08/03/2015 12:59 PM, Randy Dunlap wrote: > 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? Yes. I can change the text if you want to. > >> +# >> # 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 Fixed in my next v2. Thanks > >> + } 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; >> + > -- 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/