From a5cdaea525c32e7def563ba07d9fef9bc6edffab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= Date: Fri, 18 Feb 2022 19:16:18 +0100 Subject: scripts: kernel-doc: Add the basic POD sections MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The NAME section provides the doc title, while SYNOPSIS contains the basic syntax and usage description, which will be printed in the help document and in the error output produced on wrong script usage. The rationale is to give users simple and succinct enlightment, at the same time structuring the script internally for the maintainers. In the synopsis, Rst-only options are grouped around rst, and the rest is arranged as in the OPTIONS subsections (yet to be translated into POD, check at the end of the series). The third of the basic sections, DESCRIPTION, is added separately. Signed-off-by: Tomasz Warniełło Tested-by: Randy Dunlap Acked-by: Randy Dunlap Disliked-by: Akira Yokosawa Link: https://lore.kernel.org/r/20220218181628.1411551-2-tomasz.warniello@gmail.com Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 3106b7536b89..c8fbf1d3d5aa 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -16,6 +16,31 @@ use strict; ## This software falls under the GNU General Public License. ## ## Please read the COPYING file for more information ## +=head1 NAME + +kernel-doc - Print formatted kernel documentation to stdout + +=head1 SYNOPSIS + + kernel-doc [-h] [-v] [-Werror] + [ -man | + -rst [-sphinx-version VERSION] [-enable-lineno] | + -none + ] + [ + -export | + -internal | + [-function NAME] ... | + [-nosymbol NAME] ... + ] + [-no-doc-sections] + [-export-file FILE] ... + FILE ... + +Run `kernel-doc -h` for details. + +=cut + # 18/01/2001 - Cleanups # Functions prototyped as foo(void) same as foo() # Stop eval'ing where we don't need to. -- cgit v1.2.3 From 43caf1a6823dc7c156cf38a6c71881c1e90cd3c2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= Date: Fri, 18 Feb 2022 19:16:19 +0100 Subject: scripts: kernel-doc: Relink argument parsing error handling to pod2usage MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The former usage function is substituted, although not as the -h and -help parameter handler yet. Purpose: Use Pod::Usage to handle documentation printing in an integrated way. Signed-off-by: Tomasz Warniełło Tested-by: Randy Dunlap Acked-by: Randy Dunlap Disliked-by: Akira Yokosawa Link: https://lore.kernel.org/r/20220218181628.1411551-3-tomasz.warniello@gmail.com Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index c8fbf1d3d5aa..e7f7251771bb 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -16,6 +16,8 @@ use strict; ## This software falls under the GNU General Public License. ## ## Please read the COPYING file for more information ## +use Pod::Usage qw/pod2usage/; + =head1 NAME kernel-doc - Print formatted kernel documentation to stdout @@ -298,7 +300,13 @@ my $blankline_rst = "\n"; # read arguments if ($#ARGV == -1) { - usage(); + pod2usage( + -message => "No arguments!\n", + -exitval => 1, + -verbose => 99, + -sections => 'SYNOPSIS', + -output => \*STDERR, + ); } my $kernelversion; @@ -518,8 +526,14 @@ while ($ARGV[0] =~ m/^--?(.*)/) { die "Sphinx version should either major.minor or major.minor.patch format\n"; } } else { - # Unknown argument - usage(); + # Unknown argument + pod2usage( + -message => "Argument unknown!\n", + -exitval => 1, + -verbose => 99, + -sections => 'SYNOPSIS', + -output => \*STDERR, + ); } } -- cgit v1.2.3 From f1583922bf9383ce0079dfdded959dfc5585dc5b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= Date: Fri, 18 Feb 2022 19:16:20 +0100 Subject: scripts: kernel-doc: Translate the DESCRIPTION section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Transition the description section into POD. This is one of the standard documentation sections. This adjustment makes the section available for POD and makes it look better. Notes: - an article addition - paragraphing correction Signed-off-by: Tomasz Warniełło Tested-by: Randy Dunlap Acked-by: Randy Dunlap Disliked-by: Akira Yokosawa Link: https://lore.kernel.org/r/20220218181628.1411551-4-tomasz.warniello@gmail.com Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index e7f7251771bb..e4203f13fa93 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -41,6 +41,15 @@ kernel-doc - Print formatted kernel documentation to stdout Run `kernel-doc -h` for details. +=head1 DESCRIPTION + +Read C language source or header FILEs, extract embedded documentation comments, +and print formatted documentation to standard output. + +The documentation comments are identified by the "/**" opening comment mark. + +See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax. + =cut # 18/01/2001 - Cleanups @@ -72,12 +81,6 @@ sub usage { my $message = <<"EOF"; Usage: $0 [OPTION ...] FILE ... -Read C language source or header FILEs, extract embedded documentation comments, -and print formatted documentation to standard output. - -The documentation comments are identified by "/**" opening comment mark. See -Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax. - Output format selection (mutually exclusive): -man Output troff manual page format. This is the default. -rst Output reStructuredText format. -- cgit v1.2.3 From 2875f78708219feadf0956dcf9e936ec25fb7a8b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= Date: Fri, 18 Feb 2022 19:16:21 +0100 Subject: scripts: kernel-doc: Translate the "Output format selection" subsection of OPTIONS MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Another step in the direction of a uniform POD documentation, which will make users happier. Options land at the end of the script, not to clutter the file top. The default output format is corrected to rst. That's what it is now. A POD delimiting comment is added to the script head, which improves the script logical structure. Signed-off-by: Tomasz Warniełło Tested-by: Randy Dunlap Acked-by: Randy Dunlap Disliked-by: Akira Yokosawa Link: https://lore.kernel.org/r/20220218181628.1411551-5-tomasz.warniello@gmail.com Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 31 ++++++++++++++++++++++++++----- 1 file changed, 26 insertions(+), 5 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index e4203f13fa93..18eca172c4b5 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -52,6 +52,8 @@ See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax. =cut +# more perldoc at the end of the file + # 18/01/2001 - Cleanups # Functions prototyped as foo(void) same as foo() # Stop eval'ing where we don't need to. @@ -81,11 +83,6 @@ sub usage { my $message = <<"EOF"; Usage: $0 [OPTION ...] FILE ... -Output format selection (mutually exclusive): - -man Output troff manual page format. This is the default. - -rst Output reStructuredText format. - -none Do not output documentation, only warnings. - Output format selection modifier (affects only ReST output): -sphinx-version Use the ReST C domain dialect compatible with an @@ -2563,3 +2560,27 @@ if ($Werror && $warnings) { } else { exit($output_mode eq "none" ? 0 : $errors) } + +__END__ + +=head1 OPTIONS + +=head2 Output format selection (mutually exclusive): + +=over 8 + +=item -man + +Output troff manual page format. + +=item -rst + +Output reStructuredText format. This is the default. + +=item -none + +Do not output documentation, only warnings. + +=back + +=cut -- cgit v1.2.3 From dd803b04b0a0af16e43c2af1a3e67d7ce8e1f899 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= Date: Fri, 18 Feb 2022 19:16:22 +0100 Subject: scripts: kernel-doc: Translate the "Output format selection modifier" subsection of OPTIONS MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Aim: unified POD, user more happy This section is renamed to "Output format modifiers" to make it simple. To make it even more simple, a subsection is added: "reStructuredText only". Other notes: - paragraphing correction - article correction Signed-off-by: Tomasz Warniełło Tested-by: Randy Dunlap Acked-by: Randy Dunlap Disliked-by: Akira Yokosawa Link: https://lore.kernel.org/r/20220218181628.1411551-6-tomasz.warniello@gmail.com Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 18eca172c4b5..b926faa16b00 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -83,13 +83,6 @@ sub usage { my $message = <<"EOF"; Usage: $0 [OPTION ...] FILE ... -Output format selection modifier (affects only ReST output): - - -sphinx-version Use the ReST C domain dialect compatible with an - specific Sphinx Version. - If not specified, kernel-doc will auto-detect using - the sphinx-build version found on PATH. - Output selection (mutually exclusive): -export Only output documentation for symbols that have been exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() @@ -2583,4 +2576,19 @@ Do not output documentation, only warnings. =back +=head2 Output format modifiers + +=head3 reStructuredText only + +=over 8 + +=item -sphinx-version VERSION + +Use the ReST C domain dialect compatible with a specific Sphinx Version. + +If not specified, kernel-doc will auto-detect using the sphinx-build version +found on PATH. + +=back + =cut -- cgit v1.2.3 From 9c77f108f43ae08e560f54c817d4aeb4857dc783 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= Date: Fri, 18 Feb 2022 19:16:23 +0100 Subject: scripts: kernel-doc: Translate the "Output selection" subsection of OPTIONS MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Aim: unified POD, user more satisfied, script better structured The plurals in -function and -nosymbol are corrected to singulars. That's how the script works now. I think this describes the syntax better. The plurar suggests multiple FILE arguments might be possible. So this seems more coherent. Other notes: - paragraphing correction - article correction Signed-off-by: Tomasz Warniełło Tested-by: Randy Dunlap Acked-by: Randy Dunlap Disliked-by: Akira Yokosawa Link: https://lore.kernel.org/r/20220218181628.1411551-7-tomasz.warniello@gmail.com Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 42 +++++++++++++++++++++++++++++------------- 1 file changed, 29 insertions(+), 13 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index b926faa16b00..e49cdb307a35 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -83,19 +83,6 @@ sub usage { my $message = <<"EOF"; Usage: $0 [OPTION ...] FILE ... -Output selection (mutually exclusive): - -export Only output documentation for symbols that have been - exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() - in any input FILE or -export-file FILE. - -internal Only output documentation for symbols that have NOT been - exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() - in any input FILE or -export-file FILE. - -function NAME Only output documentation for the given function(s) - or DOC: section title(s). All other functions and DOC: - sections are ignored. May be specified multiple times. - -nosymbol NAME Exclude the specified symbols from the output - documentation. May be specified multiple times. - Output selection modifiers: -no-doc-sections Do not output DOC: sections. -enable-lineno Enable output of #define LINENO lines. Only works with @@ -2591,4 +2578,33 @@ found on PATH. =back +=head2 Output selection (mutually exclusive): + +=over 8 + +=item -export + +Only output documentation for the symbols that have been exported using +EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() in any input FILE or -export-file FILE. + +=item -internal + +Only output documentation for the symbols that have NOT been exported using +EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() in any input FILE or -export-file FILE. + +=item -function NAME + +Only output documentation for the given function or DOC: section title. +All other functions and DOC: sections are ignored. + +May be specified multiple times. + +=item -nosymbol NAME + +Exclude the specified symbol from the output documentation. + +May be specified multiple times. + +=back + =cut -- cgit v1.2.3 From c15de5a19a2881205f6f893869584c99cbe4fae4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= Date: Fri, 18 Feb 2022 19:16:24 +0100 Subject: scripts: kernel-doc: Translate the "Output selection modifiers" subsection of OPTIONS MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Aim: unified POD, user more satisfied, script better structured A subsection "reStructuredText only" is added for -enable-lineno. Other notes: - paragraphing correction Signed-off-by: Tomasz Warniełło Tested-by: Randy Dunlap Acked-by: Randy Dunlap Disliked-by: Akira Yokosawa Link: https://lore.kernel.org/r/20220218181628.1411551-8-tomasz.warniello@gmail.com Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 37 +++++++++++++++++++++++++++++-------- 1 file changed, 29 insertions(+), 8 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index e49cdb307a35..210e7e3b501b 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -83,14 +83,6 @@ sub usage { my $message = <<"EOF"; Usage: $0 [OPTION ...] FILE ... -Output selection modifiers: - -no-doc-sections Do not output DOC: sections. - -enable-lineno Enable output of #define LINENO lines. Only works with - reStructuredText format. - -export-file FILE Specify an additional FILE in which to look for - EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(). To be used with - -export or -internal. May be specified multiple times. - Other parameters: -v Verbose output, more warnings and other information. -h Print this help. @@ -2607,4 +2599,33 @@ May be specified multiple times. =back +=head2 Output selection modifiers: + +=over 8 + +=item -no-doc-sections + +Do not output DOC: sections. + +=item -export-file FILE + +Specify an additional FILE in which to look for EXPORT_SYMBOL() and +EXPORT_SYMBOL_GPL(). + +To be used with -export or -internal. + +May be specified multiple times. + +=back + +=head3 reStructuredText only + +=over 8 + +=item -enable-lineno + +Enable output of #define LINENO lines. + +=back + =cut -- cgit v1.2.3 From 834cf6b9039e6f6ebd73cc4da51cc8bc802ca777 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= Date: Fri, 18 Feb 2022 19:16:25 +0100 Subject: scripts: kernel-doc: Translate the "Other parameters" subsection of OPTIONS MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Aim: unified POD, user more satisfied, script better structured Notes: - The -help token is added. - The entries are sorted alphbetically. Signed-off-by: Tomasz Warniełło Tested-by: Randy Dunlap Acked-by: Randy Dunlap Disliked-by: Akira Yokosawa Link: https://lore.kernel.org/r/20220218181628.1411551-9-tomasz.warniello@gmail.com Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 210e7e3b501b..4a26a74318e6 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -83,11 +83,6 @@ sub usage { my $message = <<"EOF"; Usage: $0 [OPTION ...] FILE ... -Other parameters: - -v Verbose output, more warnings and other information. - -h Print this help. - -Werror Treat warnings as errors. - EOF print $message; exit 1; @@ -2628,4 +2623,22 @@ Enable output of #define LINENO lines. =back +=head2 Other parameters: + +=over 8 + +=item -h, -help + +Print this help. + +=item -v + +Verbose output, more warnings and other information. + +=item -Werror + +Treat warnings as errors. + +=back + =cut -- cgit v1.2.3 From 252b47da9fd9eeebbdaed448aea71010261d7dc4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= Date: Fri, 18 Feb 2022 19:16:26 +0100 Subject: scripts: kernel-doc: Replace the usage function MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Aim: unified POD, user more satisfied, script better structured You can see the results with: $ scripts/kernel-doc -help Signed-off-by: Tomasz Warniełło Tested-by: Randy Dunlap Acked-by: Randy Dunlap Disliked-by: Akira Yokosawa Link: https://lore.kernel.org/r/20220218181628.1411551-10-tomasz.warniello@gmail.com Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 11 +---------- 1 file changed, 1 insertion(+), 10 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 4a26a74318e6..d7ca4877eeda 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -79,15 +79,6 @@ See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax. # 25/07/2012 - Added support for HTML5 # -- Dan Luedtke -sub usage { - my $message = <<"EOF"; -Usage: $0 [OPTION ...] FILE ... - -EOF - print $message; - exit 1; -} - # # format of comments. # In the following table, (...)? signifies optional structure. @@ -468,7 +459,7 @@ while ($ARGV[0] =~ m/^--?(.*)/) { } elsif ($cmd eq "Werror") { $Werror = 1; } elsif (($cmd eq "h") || ($cmd eq "help")) { - usage(); + pod2usage(-exitval => 0, -verbose => 2); } elsif ($cmd eq 'no-doc-sections') { $no_doc_sections = 1; } elsif ($cmd eq 'enable-lineno') { -- cgit v1.2.3 From 258092a89085ed9536da00f27d8ddbe083c9ea0a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= Date: Fri, 18 Feb 2022 19:16:27 +0100 Subject: scripts: kernel-doc: Drop obsolete comments MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit What for? To improve the script maintainability. 1. License As stated by Jonathan Corbet in the reply to my version 1, the SPDX line is enough. 2. The to-do list comment As suggested by Jonathan Corbet in reply to my version 3, this section doesn't need to be transitioned. And so it is removed for clarity. 3. The historical changelog comments As suggested by Jonathan Corbet in a reply to v3, this section can go. I wanted to keep it, but since it doesn't contain copyright notices, let's just have it clean and simple. 4. The "format of comments" comment block As suggested by Jani Nikula in a reply to my first version of this transformation, Documentation/doc-guide/kernel-doc.rst can serve as the information hub for comment formatting. The section DESCRIPTION already points there, so the original comment block can just be removed. Suggested-by: Jonathan Corbet Suggested-by: Jani Nikula Signed-off-by: Tomasz Warniełło Tested-by: Randy Dunlap Acked-by: Randy Dunlap Disliked-by: Akira Yokosawa Link: https://lore.kernel.org/r/20220218181628.1411551-11-tomasz.warniello@gmail.com Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 143 ----------------------------------------------------- 1 file changed, 143 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index d7ca4877eeda..a5a397e22ea7 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -12,9 +12,6 @@ use strict; ## ## ## #define enhancements by Armin Kuster ## ## Copyright (c) 2000 MontaVista Software, Inc. ## -## ## -## This software falls under the GNU General Public License. ## -## Please read the COPYING file for more information ## use Pod::Usage qw/pod2usage/; @@ -54,146 +51,6 @@ See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax. # more perldoc at the end of the file -# 18/01/2001 - Cleanups -# Functions prototyped as foo(void) same as foo() -# Stop eval'ing where we don't need to. -# -- huggie@earth.li - -# 27/06/2001 - Allowed whitespace after initial "/**" and -# allowed comments before function declarations. -# -- Christian Kreibich - -# Still to do: -# - add perldoc documentation -# - Look more closely at some of the scarier bits :) - -# 26/05/2001 - Support for separate source and object trees. -# Return error code. -# Keith Owens - -# 23/09/2001 - Added support for typedefs, structs, enums and unions -# Support for Context section; can be terminated using empty line -# Small fixes (like spaces vs. \s in regex) -# -- Tim Jansen - -# 25/07/2012 - Added support for HTML5 -# -- Dan Luedtke - -# -# format of comments. -# In the following table, (...)? signifies optional structure. -# (...)* signifies 0 or more structure elements -# /** -# * function_name(:)? (- short description)? -# (* @parameterx: (description of parameter x)?)* -# (* a blank line)? -# * (Description:)? (Description of function)? -# * (section header: (section description)? )* -# (*)?*/ -# -# So .. the trivial example would be: -# -# /** -# * my_function -# */ -# -# If the Description: header tag is omitted, then there must be a blank line -# after the last parameter specification. -# e.g. -# /** -# * my_function - does my stuff -# * @my_arg: its mine damnit -# * -# * Does my stuff explained. -# */ -# -# or, could also use: -# /** -# * my_function - does my stuff -# * @my_arg: its mine damnit -# * Description: Does my stuff explained. -# */ -# etc. -# -# Besides functions you can also write documentation for structs, unions, -# enums and typedefs. Instead of the function name you must write the name -# of the declaration; the struct/union/enum/typedef must always precede -# the name. Nesting of declarations is not supported. -# Use the argument mechanism to document members or constants. -# e.g. -# /** -# * struct my_struct - short description -# * @a: first member -# * @b: second member -# * -# * Longer description -# */ -# struct my_struct { -# int a; -# int b; -# /* private: */ -# int c; -# }; -# -# 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 -# empty line. -# A non-void function should have a "Return:" section describing the return -# value(s). -# Example-sections should contain the string EXAMPLE so that they are marked -# appropriately in DocBook. -# -# Example: -# /** -# * user_function - function that can only be called in user context -# * @a: some argument -# * Context: !in_interrupt() -# * -# * Some description -# * Example: -# * user_function(22); -# */ -# ... -# -# -# All descriptive text is further processed, scanning for the following special -# patterns, which are highlighted appropriately. -# -# 'funcname()' - function -# '$ENVVAR' - environmental variable -# '&struct_name' - name of a structure (up to two words including 'struct') -# '&struct_name.member' - name of a structure member -# '@parameter' - name of a parameter -# '%CONST' - name of a constant. -# '``LITERAL``' - literal string without any spaces on it. - ## init lots of data my $errors = 0; -- cgit v1.2.3 From 2b306ecaf57b2b5004dcb671a46ef24a1c369db2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20Warnie=C5=82=C5=82o?= Date: Fri, 18 Feb 2022 19:16:28 +0100 Subject: scripts: kernel-doc: Refresh the copyright lines MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit I wanted to clean up these lines, but in the end decided not to touch the old ones and just add my own about POD. I'll leave the cleanup for lawyers. Signed-off-by: Tomasz Warniełło Tested-by: Randy Dunlap Acked-by: Randy Dunlap Disliked-by: Akira Yokosawa Link: https://lore.kernel.org/r/20220218181628.1411551-12-tomasz.warniello@gmail.com Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 2 ++ 1 file changed, 2 insertions(+) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index a5a397e22ea7..f06f68f3c3d9 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -12,6 +12,8 @@ use strict; ## ## ## #define enhancements by Armin Kuster ## ## Copyright (c) 2000 MontaVista Software, Inc. ## +# +# Copyright (C) 2022 Tomasz Warniełło (POD) use Pod::Usage qw/pod2usage/; -- cgit v1.2.3 From e334f873eb4e1638dd0b45200d2d8838a13b0cac Mon Sep 17 00:00:00 2001 From: Akira Yokosawa Date: Thu, 24 Feb 2022 22:02:46 +0900 Subject: docs: scripts/kernel-doc: Detect absence of FILE arg Currently, when there is no FILE argument following a switch such as -man, -rst, or -none, kernel-doc exits with a warning from perl (long msg folded): Use of uninitialized value $ARGV[0] in pattern match (m//) at ./scripts/kernel-doc line 438. , which is unhelpful. Improve the behavior by adding a check at the bottom of parsing loop. If the argument is absent, display help text and exit with the code of 1 (via usage()). Signed-off-by: Akira Yokosawa Cc: Randy Dunlap Link: https://lore.kernel.org/r/7b136049-a3ba-0eb5-8717-364d773ff914@gmail.com [jc: reworked to fix conflict with pod patches] Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index f06f68f3c3d9..9c084a2ba3b0 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -343,14 +343,23 @@ while ($ARGV[0] =~ m/^--?(.*)/) { die "Sphinx version should either major.minor or major.minor.patch format\n"; } } else { - # Unknown argument - pod2usage( - -message => "Argument unknown!\n", - -exitval => 1, - -verbose => 99, - -sections => 'SYNOPSIS', - -output => \*STDERR, - ); + # Unknown argument + pod2usage( + -message => "Argument unknown!\n", + -exitval => 1, + -verbose => 99, + -sections => 'SYNOPSIS', + -output => \*STDERR, + ); + } + if ($#ARGV < 0){ + pod2usage( + -message => "FILE argument missing\n", + -exitval => 1, + -verbose => 99, + -sections => 'SYNOPSIS', + -output => \*STDERR, + ); } } -- cgit v1.2.3