[PATCH] scripts: kernel-doc: transform documentation into POD

[PATCH] scripts: kernel-doc: transform documentation into POD

[Tomasz Warniełło]

The only change in the script execution flow is the replacement
of the 'usage' function with the native core Perl 'pod2usage'.

This entails:
- an overall documentation restructuring
- addition of a synopsis

Otherwise my intervention is minimal:
- a few tiny language, formatting and spacing corrections
- a few missing bits added in the command syntax description
- adding subsections in the "FORMAT OF COMMENTS" section
- alphabetical sorting within OPTIONS subections

Finally, the TODO stub evolves into a section:
- perldoc request removed
- undocumented options added

Run `kernel-doc -h` to see the full doc.

The TODO suggestion is ancient, thus I can't address its author with
a "Suggested-by" tag.

Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
---
 scripts/kernel-doc | 613 ++++++++++++++++++++++++++++++---------------
 1 file changed, 413 insertions(+), 200 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 3106b7536b89..00c0c7f5ff58 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -4,46 +4,33 @@
 use warnings;
 use strict;
 
-## Copyright (c) 1998 Michael Zucchi, All Rights Reserved        ##
-## Copyright (C) 2000, 1  Tim Waugh <twaugh@redhat.com>          ##
-## Copyright (C) 2001  Simon Huggins                             ##
-## Copyright (C) 2005-2012  Randy Dunlap                         ##
-## Copyright (C) 2012  Dan Luedtke                               ##
-## 								 ##
-## #define enhancements by Armin Kuster <akuster@mvista.com>	 ##
-## Copyright (c) 2000 MontaVista Software, Inc.			 ##
-## 								 ##
-## This software falls under the GNU General Public License.     ##
-## Please read the COPYING file for more information             ##
-
-# 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 <ck@whoop.org>
-
-# 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 <kaos@ocs.com.au>
-
-# 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 <tim@tjansen.de>
-
-# 25/07/2012 - Added support for HTML5
-# -- Dan Luedtke <mail@danrl.de>
-
-sub usage {
-    my $message = <<"EOF";
-Usage: $0 [OPTION ...] FILE ...
+use Pod::Usage qw/pod2usage/;
+
+=head1 NAME
+
+kernel-doc - Print formatted kernel documentation to stdout.
+
+=head1 SYNOPSIS
+
+ kernel-doc [-h] [-v] [-Werror]
+   [-man|-none|-rst]
+   [-sphinx-version VERSION]
+   [
+     -export |
+     [-function NAME] ... |
+     -internal |
+     [-nosymbol NAME] ...
+   ]
+   [-enable-lineno]
+   [-export-file FILE] ...
+   [-no-doc-sections]
+   FILE ...
+
+Run `kernel-doc -h` for details.
+
+=cut
+
+=head1 DESCRIPTION
 
 Read C language source or header FILEs, extract embedded documentation comments,
 and print formatted documentation to standard output.
@@ -51,163 +38,9 @@ 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.
-  -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
-			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()
-                        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
-                        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.
-  -Werror		Treat warnings as errors.
-
-EOF
-    print $message;
-    exit 1;
-}
+=cut
 
-#
-# 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.
+# more perldoc at the end of the file
 
 ## init lots of data
 
@@ -273,7 +106,12 @@ my $blankline_rst = "\n";
 
 # read arguments
 if ($#ARGV == -1) {
-    usage();
+	pod2usage(
+		-message => "No arguments!\n",
+		-exitval => 1,
+		-verbose => 99,
+		-sections => 'SYNOPSIS'
+	);
 }
 
 my $kernelversion;
@@ -468,7 +306,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') {
@@ -493,8 +331,13 @@ 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'
+			);
     }
 }
 
@@ -2521,3 +2364,373 @@ 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. This is the default.
+
+=item -none
+
+Do not output documentation, only warnings.
+
+=item -rst
+
+Output reStructuredText format.
+
+=back
+
+=head2 Output format selection modifier (affects only ReST output):
+
+=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
+
+=head2 Output selection (mutually exclusive):
+
+=over 8
+
+=item -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.
+
+=item -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.
+
+=item -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.
+
+=item -nosymbol NAME
+
+Exclude the specified symbols from the output documentation.
+
+May be specified multiple times.
+
+=back
+
+=head2 Output selection modifiers:
+
+=over 8
+
+=item -enable-lineno
+
+Enable output of #define LINENO lines. Only works with reStructuredText format.
+
+=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.
+
+=item -no-doc-sections
+
+Do not output DOC: sections.
+
+=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
+
+=head1 FORMAT OF COMMENTS
+
+=head2 Functions
+
+=over 8
+
+=item In the following table,
+
+=over 8
+
+=item (...)?
+
+signifies optional structure,
+
+=item	(...)*
+
+signifies 0 or more structure elements.
+
+=back
+
+=back
+
+ /**
+  * 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.
+
+=head2 Structs, unions, enums and typedefs
+
+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.
+
+e.g.
+
+ /**
+  * 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 used only for struct/enum members.
+
+=head2 Additional sections
+
+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 from 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.
+
+=over 8
+
+=item 'funcname()'
+
+function
+
+=item '$ENVVAR'
+
+environmental variable
+
+=item '&struct_name'
+
+name of a structure (up to two words including 'struct')
+
+=item '&struct_name.member'
+
+name of a structure member
+
+=item '@parameter'
+
+name of a parameter
+
+=item '%CONST'
+
+name of a constant
+
+=item '``LITERAL``'
+
+literal string without any spaces on it
+
+=back
+
+=cut
+
+=head1 TODO
+
+=head2 General
+
+=over 2
+
+=item -
+
+Look more closely at some of the scarier bits :)
+
+=back
+
+=head2 Options
+
+=over 2
+
+=item -
+
+Document: -module NAME, -show-not-found
+
+=back
+
+=head1 LICENSE
+
+This software falls under the GNU General Public License.
+
+Please read the COPYING file for more information.
+
+=head1 COPYRIGHT
+
+=over 2
+
+=item *
+
+Copyright (C) 1998 Michael Zucchi, All Rights Reserved
+
+=item *
+
+Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com>
+
+=item *
+
+Copyright (C) 2001 Simon Huggins
+
+=item *
+
+Copyright (C) 2005-2012 Randy Dunlap
+
+=item *
+
+Copyright (C) 2012 Dan Luedtke
+
+=item *
+
+Copyright (C) 2000 MontaVista Software, Inc.
+
+#define enhancements by Armin Kuster <akuster@mvista.com>
+
+=back
+
+=head1 SOME PRE-GIT CONTRIBUTIONS
+
+Original formatting preserved for its historical value.
+
+ # 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 <ck@whoop.org>
+
+ # 26/05/2001 - 	Support for separate source and object trees.
+ #		Return error code.
+ # 		Keith Owens <kaos@ocs.com.au>
+
+ # 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 <tim@tjansen.de>
+
+ # 25/07/2012 - Added support for HTML5
+ # -- Dan Luedtke <mail@danrl.de>
+
+=cut
-- 
2.30.2

Re: [PATCH] scripts: kernel-doc: transform documentation into POD

[Jonathan Corbet]

Tomasz Warniełło <tomasz.warniello@gmail.com> writes:

> The only change in the script execution flow is the replacement
> of the 'usage' function with the native core Perl 'pod2usage'.
>
> This entails:
> - an overall documentation restructuring
> - addition of a synopsis
>
> Otherwise my intervention is minimal:
> - a few tiny language, formatting and spacing corrections
> - a few missing bits added in the command syntax description
> - adding subsections in the "FORMAT OF COMMENTS" section
> - alphabetical sorting within OPTIONS subections

So I think that this is generally a good thing, but I do have some
quibbles.  Starting with the above, which is a pretty clear violation of
the "each patch does one thing" rule.  Please separate out your changes
into separate patches so that they are more easily reviewed.

A few other things below...

> Finally, the TODO stub evolves into a section:
> - perldoc request removed
> - undocumented options added
>
> Run `kernel-doc -h` to see the full doc.
>
> The TODO suggestion is ancient, thus I can't address its author with
> a "Suggested-by" tag.
>
> Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
> ---
>  scripts/kernel-doc | 613 ++++++++++++++++++++++++++++++---------------
>  1 file changed, 413 insertions(+), 200 deletions(-)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 3106b7536b89..00c0c7f5ff58 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -4,46 +4,33 @@
>  use warnings;
>  use strict;
>  
> -## Copyright (c) 1998 Michael Zucchi, All Rights Reserved        ##
> -## Copyright (C) 2000, 1  Tim Waugh <twaugh@redhat.com>          ##
> -## Copyright (C) 2001  Simon Huggins                             ##
> -## Copyright (C) 2005-2012  Randy Dunlap                         ##
> -## Copyright (C) 2012  Dan Luedtke                               ##
> -## 								 ##
> -## #define enhancements by Armin Kuster <akuster@mvista.com>	 ##
> -## Copyright (c) 2000 MontaVista Software, Inc.			 ##

My immediate reaction is that you shouldn't be removing copyright lines,
though I did see that you put them back later.  I think, though, that
the copyright assertions should remain at the top of the file; they
don't need to be part of the help text that the program emits.  So leave
them here, please.

(I guess I should add one of my own, assuming I want any part of this
file actually associated with my name...:)

> -## This software falls under the GNU General Public License.     ##
> -## Please read the COPYING file for more information             ##

This could come out, though; that's what the SPDX line is for.

> -# 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 <ck@whoop.org>
> -
> -# 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 <kaos@ocs.com.au>
> -
> -# 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 <tim@tjansen.de>
> -
> -# 25/07/2012 - Added support for HTML5
> -# -- Dan Luedtke <mail@danrl.de>

These, too, should come out; that's what the git log is for.

[...]

>  my $kernelversion;
> @@ -468,7 +306,7 @@ while ($ARGV[0] =~ m/^--?(.*)/) {
>      } elsif ($cmd eq "Werror") {
>  	$Werror = 1;
>      } elsif (($cmd eq "h") || ($cmd eq "help")) {
> -	usage();
> +			pod2usage(-exitval => 0, -verbose => 2);

Why the strange indentation here?  This file is far from pretty, but
that makes it worse.  (Other places too).

[...]

Thanks,

jon

Re: [PATCH] scripts: kernel-doc: transform documentation into POD

[Jani Nikula]

On Thu, 16 Dec 2021, Jonathan Corbet <corbet@lwn.net> wrote:
> Tomasz Warniełło <tomasz.warniello@gmail.com> writes:
>
>> The only change in the script execution flow is the replacement
>> of the 'usage' function with the native core Perl 'pod2usage'.
>>
>> This entails:
>> - an overall documentation restructuring
>> - addition of a synopsis
>>
>> Otherwise my intervention is minimal:
>> - a few tiny language, formatting and spacing corrections
>> - a few missing bits added in the command syntax description
>> - adding subsections in the "FORMAT OF COMMENTS" section
>> - alphabetical sorting within OPTIONS subections
>
> So I think that this is generally a good thing, but I do have some
> quibbles.  Starting with the above, which is a pretty clear violation of
> the "each patch does one thing" rule.  Please separate out your changes
> into separate patches so that they are more easily reviewed.
>
> A few other things below...

I'd throw all code comment formatting documentation out of here, and
restrict the script to describing the command-line parameters only, and
focus on Documentation/doc-guide/kernel-doc.rst being the single point
of truth for comment formatting.


BR,
Jani.

>
>> Finally, the TODO stub evolves into a section:
>> - perldoc request removed
>> - undocumented options added
>>
>> Run `kernel-doc -h` to see the full doc.
>>
>> The TODO suggestion is ancient, thus I can't address its author with
>> a "Suggested-by" tag.
>>
>> Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
>> ---
>>  scripts/kernel-doc | 613 ++++++++++++++++++++++++++++++---------------
>>  1 file changed, 413 insertions(+), 200 deletions(-)
>>
>> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
>> index 3106b7536b89..00c0c7f5ff58 100755
>> --- a/scripts/kernel-doc
>> +++ b/scripts/kernel-doc
>> @@ -4,46 +4,33 @@
>>  use warnings;
>>  use strict;
>>  
>> -## Copyright (c) 1998 Michael Zucchi, All Rights Reserved        ##
>> -## Copyright (C) 2000, 1  Tim Waugh <twaugh@redhat.com>          ##
>> -## Copyright (C) 2001  Simon Huggins                             ##
>> -## Copyright (C) 2005-2012  Randy Dunlap                         ##
>> -## Copyright (C) 2012  Dan Luedtke                               ##
>> -## 								 ##
>> -## #define enhancements by Armin Kuster <akuster@mvista.com>	 ##
>> -## Copyright (c) 2000 MontaVista Software, Inc.			 ##
>
> My immediate reaction is that you shouldn't be removing copyright lines,
> though I did see that you put them back later.  I think, though, that
> the copyright assertions should remain at the top of the file; they
> don't need to be part of the help text that the program emits.  So leave
> them here, please.
>
> (I guess I should add one of my own, assuming I want any part of this
> file actually associated with my name...:)
>
>> -## This software falls under the GNU General Public License.     ##
>> -## Please read the COPYING file for more information             ##
>
> This could come out, though; that's what the SPDX line is for.
>
>> -# 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 <ck@whoop.org>
>> -
>> -# 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 <kaos@ocs.com.au>
>> -
>> -# 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 <tim@tjansen.de>
>> -
>> -# 25/07/2012 - Added support for HTML5
>> -# -- Dan Luedtke <mail@danrl.de>
>
> These, too, should come out; that's what the git log is for.
>
> [...]
>
>>  my $kernelversion;
>> @@ -468,7 +306,7 @@ while ($ARGV[0] =~ m/^--?(.*)/) {
>>      } elsif ($cmd eq "Werror") {
>>  	$Werror = 1;
>>      } elsif (($cmd eq "h") || ($cmd eq "help")) {
>> -	usage();
>> +			pod2usage(-exitval => 0, -verbose => 2);
>
> Why the strange indentation here?  This file is far from pretty, but
> that makes it worse.  (Other places too).
>
> [...]
>
> Thanks,
>
> jon

-- 
Jani Nikula, Intel Open Source Graphics Center

Re: [PATCH] scripts: kernel-doc: transform documentation into POD

[Tomasz Warniełło]

On 17/12/2021 00:12, Jonathan Corbet wrote:
>>  my $kernelversion;
>> @@ -468,7 +306,7 @@ while ($ARGV[0] =~ m/^--?(.*)/) {
>>      } elsif ($cmd eq "Werror") {
>>  	$Werror = 1;
>>      } elsif (($cmd eq "h") || ($cmd eq "help")) {
>> -	usage();
>> +			pod2usage(-exitval => 0, -verbose => 2);
> 
> Why the strange indentation here?  This file is far from pretty, but
> that makes it worse.  (Other places too).

Sometimes beauty requires cooperation. You can help it in your pager.
If it's less, then try `-x 2`, `-x 4`, etc.

I will address the other topics in a new version. To be sent shortly.

Tx, TW

Re: [PATCH] scripts: kernel-doc: transform documentation into POD

[Jani Nikula]

On Mon, 03 Jan 2022, Tomasz Warniełło <tomasz.warniello@gmail.com> wrote:
> On 17/12/2021 00:12, Jonathan Corbet wrote:
>>>  my $kernelversion;
>>> @@ -468,7 +306,7 @@ while ($ARGV[0] =~ m/^--?(.*)/) {
>>>      } elsif ($cmd eq "Werror") {
>>>  	$Werror = 1;
>>>      } elsif (($cmd eq "h") || ($cmd eq "help")) {
>>> -	usage();
>>> +			pod2usage(-exitval => 0, -verbose => 2);
>> 
>> Why the strange indentation here?  This file is far from pretty, but
>> that makes it worse.  (Other places too).
>
> Sometimes beauty requires cooperation. You can help it in your pager.
> If it's less, then try `-x 2`, `-x 4`, etc.

In kernel, tabs are 8 characters.

See Documentation/process/coding-style.rst


BR,
Jani.


-- 
Jani Nikula, Intel Open Source Graphics Center

Re: [PATCH] scripts: kernel-doc: transform documentation into POD

[Tomasz Warniełło]

On Mon, 03 Jan 2022 11:04:53 +0200
Jani Nikula <jani.nikula@linux.intel.com> wrote:

> On Mon, 03 Jan 2022, Tomasz Warniełło <tomasz.warniello@gmail.com> wrote:
> > On 17/12/2021 00:12, Jonathan Corbet wrote:  
> >>>  my $kernelversion;
> >>> @@ -468,7 +306,7 @@ while ($ARGV[0] =~ m/^--?(.*)/) {
> >>>      } elsif ($cmd eq "Werror") {
> >>>  	$Werror = 1;
> >>>      } elsif (($cmd eq "h") || ($cmd eq "help")) {
> >>> -	usage();
> >>> +			pod2usage(-exitval => 0, -verbose => 2);  
> >> 
> >> Why the strange indentation here?  This file is far from pretty, but
> >> that makes it worse.  (Other places too).  
> >
> > Sometimes beauty requires cooperation. You can help it in your pager.
> > If it's less, then try `-x 2`, `-x 4`, etc.  
> 
> In kernel, tabs are 8 characters.
> 
> See Documentation/process/coding-style.rst
> 
> 
> BR,
> Jani.
> 
> 

I am a heretic then.

Except for the initial dogma, I understand and agree with the rationale
in coding-style.rst.

Only what if I have stared at the screen not for 20 hours, but for
40 hours? Now I want to have indentation even deeper, of 16 spaces.
And how do I get this having 8 spaces here and there instead of tabs?
The system begins to fall apart.

The misleading statement is that tabs are 8 characters long. No. They
are exactly 1 character long. And that's ASCII 9.

Cheers,
TW

Re: [PATCH] scripts: kernel-doc: transform documentation into POD

[Jonathan Corbet]

Tomasz Warniełło <tomasz.warniello@gmail.com> writes:

> On Mon, 03 Jan 2022 11:04:53 +0200
> Jani Nikula <jani.nikula@linux.intel.com> wrote:
>> In kernel, tabs are 8 characters.
>> 
>> See Documentation/process/coding-style.rst
>> 
>
> I am a heretic then.
>
> Except for the initial dogma, I understand and agree with the rationale
> in coding-style.rst.
>
> Only what if I have stared at the screen not for 20 hours, but for
> 40 hours? Now I want to have indentation even deeper, of 16 spaces.
> And how do I get this having 8 spaces here and there instead of tabs?
> The system begins to fall apart.
>
> The misleading statement is that tabs are 8 characters long. No. They
> are exactly 1 character long. And that's ASCII 9.

This is not particularly helpful.

I would like to get your work in, but need some cooperation to get
there.

Please:

 - Post your patch series as a single thread with a coherent cover
   letter.

 - Stick with current coding conventions

 - Avoid snide comments to reviewers.

Thanks,

jon

Re: [PATCH] scripts: kernel-doc: transform documentation into POD

[Mauro Carvalho Chehab]

Em Thu, 16 Dec 2021 16:12:15 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:

> Tomasz Warniełło <tomasz.warniello@gmail.com> writes:
> 
> > The only change in the script execution flow is the replacement
> > of the 'usage' function with the native core Perl 'pod2usage'.
> >
> > This entails:
> > - an overall documentation restructuring
> > - addition of a synopsis
> >
> > Otherwise my intervention is minimal:
> > - a few tiny language, formatting and spacing corrections
> > - a few missing bits added in the command syntax description
> > - adding subsections in the "FORMAT OF COMMENTS" section
> > - alphabetical sorting within OPTIONS subections  
> 
> So I think that this is generally a good thing, but I do have some
> quibbles.  Starting with the above, which is a pretty clear violation of
> the "each patch does one thing" rule.  Please separate out your changes
> into separate patches so that they are more easily reviewed.

I almost did that in the past, but due to a different rationale ;-)

Besides the points that Jonathan already mentioned, I'd like to add
one additional request...

Pod is very useful when associated with Getopt, e. g.:

	use Getopt::Long;
	use Pod::Usage;

In a similar way to scripts/get_abi.pl (and scripts/get_feat.pl).

This simplifies a lot the parameter handling, as it would
be like:

	GetOptions(
		"debug=i" => \$debug,
		"enable-lineno" => \$enable_lineno,
		"rst-source!" => \$description_is_rst,
		"dir=s" => \$prefix,
		'help|?' => \$help,
		"show-hints" => \$hint,
		"search-string=s" => \$search_string,
		man => \$man
	) or pod2usage(2);

This would make easier to maintain the parameters and the associated
summary help and man-like help. An additional advantage of using Getopt
is that the parameters can be added before or after the file name.

IMO, the best would be to add a patch at the version 2 of this series
in order to use GetOpt too.

> A few other things below...
> 
> > Finally, the TODO stub evolves into a section:
> > - perldoc request removed
> > - undocumented options added
> >
> > Run `kernel-doc -h` to see the full doc.
> >
> > The TODO suggestion is ancient, thus I can't address its author with
> > a "Suggested-by" tag.
> >
> > Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
> > ---
> >  scripts/kernel-doc | 613 ++++++++++++++++++++++++++++++---------------
> >  1 file changed, 413 insertions(+), 200 deletions(-)
> >
> > diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> > index 3106b7536b89..00c0c7f5ff58 100755
> > --- a/scripts/kernel-doc
> > +++ b/scripts/kernel-doc
> > @@ -4,46 +4,33 @@
> >  use warnings;
> >  use strict;

I would also add:

	BEGIN { $Pod::Usage::Formatter = 'Pod::Text::Termcap'; }

at the final version, in order to produce a better output.

Regards,
Mauro


Thanks,
Mauro

Re: [PATCH] scripts: kernel-doc: transform documentation into POD

[Tomasz Warniełło]

On Mon, 03 Jan 2022 13:04:09 -0700
Jonathan Corbet <corbet@lwn.net> wrote:

> Tomasz Warniełło <tomasz.warniello@gmail.com> writes:
> 
> > On Mon, 03 Jan 2022 11:04:53 +0200
> > Jani Nikula <jani.nikula@linux.intel.com> wrote:  
> >> In kernel, tabs are 8 characters.
> >> 
> >> See Documentation/process/coding-style.rst
> >>   
> >
> > I am a heretic then.
> >
> > Except for the initial dogma, I understand and agree with the rationale
> > in coding-style.rst.
> >
> > Only what if I have stared at the screen not for 20 hours, but for
> > 40 hours? Now I want to have indentation even deeper, of 16 spaces.
> > And how do I get this having 8 spaces here and there instead of tabs?
> > The system begins to fall apart.
> >
> > The misleading statement is that tabs are 8 characters long. No. They
> > are exactly 1 character long. And that's ASCII 9.  
> 
> This is not particularly helpful.

Not helpful? In what matter? It is a matter of fact opinion on
coding-style.rst, which Jani Nikula referred to, so I think it is both
in topic and may be helpful to some. While troublesome to some others,
that's true.

> I would like to get your work in, but need some cooperation to get
> there.
> 
> Please:
> 
>  - Post your patch series as a single thread with a coherent cover
>    letter.

Sorry, I'm a newbie in this business. I need to figure out how emails
work. Is this just one thread per version or one thread per all versions?
Can you please direct me to some documentation about this?

>  - Stick with current coding conventions

To be honest, I need to think this over.

>  - Avoid snide comments to reviewers.

My reply is no more snide than coding-style.rst. Compare them. It strictly
relates to it. I don't point my answer at the reviewer in any way, if that's
what you mean.

Ch, TW

Re: [PATCH] scripts: kernel-doc: transform documentation into POD

[Jonathan Corbet]

Tomasz Warniełło <tomasz.warniello@gmail.com> writes:

>>  - Post your patch series as a single thread with a coherent cover
>>    letter.
>
> Sorry, I'm a newbie in this business. I need to figure out how emails
> work. Is this just one thread per version or one thread per all versions?
> Can you please direct me to some documentation about this?

One thread per version is good; please do not post new versions to old
threads.  A tool like "git send-email" can be your friend here.  See
Documentation/process/submitting-patches.rst for lots of details on how
to submit patches.

Along these lines, I appreciate that you broke up the series as I
requested, but you overdid it a bit.  Think in terms of logical changes
and making things easy to review, and you should be able to coalesce
things a bit.

>>  - Stick with current coding conventions
>
> To be honest, I need to think this over.

Think hard; if you're unable to work with the kernel project's
conventions, there's not a lot of point in resubmitting the patches. 

Thanks,

jon

Re: [PATCH] scripts: kernel-doc: transform documentation into POD

[Tomasz Warniełło]

On Mon, 03 Jan 2022 14:57:48 -0700
Jonathan Corbet <corbet@lwn.net> wrote:

> One thread per version is good; please do not post new versions to old
> threads.  A tool like "git send-email" can be your friend here.  See
> Documentation/process/submitting-patches.rst for lots of details on how
> to submit patches.

Ok, thanks. I'll try to do it correctly this time...

> Along these lines, I appreciate that you broke up the series as I
> requested, but you overdid it a bit.  Think in terms of logical changes
> and making things easy to review, and you should be able to coalesce
> things a bit.

I'm not good at guessing what seems logical to others, especially those I
don't know much. No sarcasm here. Luckily it's not that many of them, so
hopefully they'll pass the exam overdone as they are.

> >>  - Stick with current coding conventions  
> >
> > To be honest, I need to think this over.  
> 
> Think hard; if you're unable to work with the kernel project's
> conventions, there's not a lot of point in resubmitting the patches. 

Let's finish this one together.

As for the actual code corrections, I see I put 1 tab too many in
two places in the last version. So I guess I just need to reduce them
by 1? No sarcasm again... So let me know before I've sent the next version,
if you please.

Ch, TW