Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]
Groups > linux.kernel > #1199590 > unrolled thread
| Started by | Daniel Vetter <daniel@ffwll.ch> |
|---|---|
| First post | 2015-08-04 11:10 +0200 |
| Last post | 2015-08-06 21:20 +0200 |
| Articles | 3 — 3 participants |
Back to article view | Back to linux.kernel
This discussion starts older than the indexed window; earlier articles aren't shown. The article labeled Started by
below is the oldest one visible, not the original post.
Re: [PATCH] scripts/kernel-doc Allow struct arguments documentation in struct body Daniel Vetter <daniel@ffwll.ch> - 2015-08-04 11:10 +0200
[PATCH v2] scripts/kernel-doc Allow struct arguments documentation in struct body Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> - 2015-08-04 14:10 +0200
Re: [PATCH v2] scripts/kernel-doc Allow struct arguments documentation in struct body Jonathan Corbet <corbet@lwn.net> - 2015-08-06 21:20 +0200
| From | Daniel Vetter <daniel@ffwll.ch> |
|---|---|
| Date | 2015-08-04 11:10 +0200 |
| Subject | Re: [PATCH] scripts/kernel-doc Allow struct arguments documentation in struct body |
| Message-ID | <pTGor-60Z-41@gated-at.bofh.it> |
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 <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>
> ---
> 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/
[toc] | [next] | [standalone]
| From | Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> |
|---|---|
| Date | 2015-08-04 14:10 +0200 |
| Subject | [PATCH v2] scripts/kernel-doc Allow struct arguments documentation in struct body |
| Message-ID | <pTJcF-1D3-71@gated-at.bofh.it> |
| In reply to | #1199590 |
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);
--
2.4.6
--
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/
[toc] | [prev] | [next] | [standalone]
| From | Jonathan Corbet <corbet@lwn.net> |
|---|---|
| Date | 2015-08-06 21:20 +0200 |
| Subject | Re: [PATCH v2] scripts/kernel-doc Allow struct arguments documentation in struct body |
| Message-ID | <pUyRP-1mX-17@gated-at.bofh.it> |
| In reply to | #1199742 |
On Tue, 4 Aug 2015 09:04:08 -0300 Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> 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. OK, this change has been merged into the docs tree. Thanks, jon -- 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/
[toc] | [prev] | [standalone]
Back to top | Article view | linux.kernel
csiph-web