[PATCH v3 00/15] Transform documentation into POD

[PATCH v3 00/15] Transform documentation into POD

[Tomasz Warniełło]

This series transforms the free-form general comments - mainly the usage
instructions and the meta information - into the standard Perl
documentation format. Some of the original text is reduced out.

The transformation includes language, paragraphing and editorial
corrections.

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

The TODO suggestion to write POD found in the script is ancient, thus
I can't address its author with a "Suggested-by" tag.

The process consists of 15 steps.

Patches beginning with no 4 are disfunctional until no 10 has been
applied.

This version is in fact the first correction of v1. The first attempt to
send it was a failure due to my lack of experience. It was weird in other
ways too. Never mind the details.

What I'm sending now mostly follows the advice received for v1. My reply is
contained in the patches otherwise. I have also done a few bits differently
to v1, as I found better solutions, etc.

Ok, let's see how it gets through this time.

PS. Jani Nikula and Jonathan Corbet - sorry for bothering you with a copy of
		emails with you tagged in them that I sent to myself. This was unexpected.

Tomasz Warniełło (15):
  scripts: kernel-doc: Add the NAME section
  scripts: kernel-doc: Add the SYNOPSIS section
  scripts: kernel-doc: Relink argument parsing error handling to
    pod2usage
  scripts: kernel-doc: Translate the DESCRIPTION section
  scripts: kernel-doc: Translate the "Output format selection"
    subsection of OPTIONS
  scripts: kernel-doc: Translate the "Output format selection modifier"
    subsection of OPTIONS
  scripts: kernel-doc: Translate the "Output selection" subsection of
    OPTIONS
  scripts: kernel-doc: Translate the "Output selection modifiers"
    subsection of OPTIONS
  scripts: kernel-doc: Translate the "Other parameters" subsection of
    OPTIONS
  scripts: kernel-doc: Replace the usage function
  scripts: kernel-doc: Remove the "format of comments" comment block
  scripts: kernel-doc: Archive the pre-git museum
  scripts: kernel-doc: License cleanup
  scripts: kernel-doc: Refresh the copyright lines
  scripts: kernel-doc: Move the TODOs

 scripts/kernel-doc | 390 ++++++++++++++++++++++-----------------------
 1 file changed, 194 insertions(+), 196 deletions(-)


base-commit: 2a987e65025e2b79c6d453b78cb5985ac6e5eb26
-- 
2.30.2

[PATCH v3 01/15] scripts: kernel-doc: Add the NAME section

[Tomasz Warniełło]

You can see the POD with:

$ perldoc scripts/kernel-doc

* Transform documentation into POD (1/15)
= Series explanation =

This series transforms the free-form general comments - mainly the usage
instructions and the meta information - into the standard Perl
documentation format. Some of the original text is reduced out.

The transformation includes language, paragraphing and editorial
corrections.

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

The TODO suggestion to write POD found in the script is ancient, thus
I can't address its author with a "Suggested-by" tag.

The process consists of 15 steps.

1) Add the NAME section
2) Add the SYNOPSIS section
3) Relink argument parsing error handling to pod2usage

The following subseries is disfunctional before its last part.

4) Translate the DESCRIPTION section
5) Translate the "Output format selection" subsection of OPTIONS
6) Translate the "Output format selection modifier" subsection of OPTIONS
7) Translate the "Output selection" subsection of OPTIONS
8) Translate the "Output selection modifiers" subsection of OPTIONS
9) Translate the "Other parameters" subsection of OPTIONS
10) Replace the usage function

Here the DESCRIPTION and OPTIONS subseries is finished. The -h and -help
parameters are handled by POD now.

11) Remove the "format of comments" comment block
12) Archive the pre-git museum
13) License cleanup
14) Refresh the copyright lines
15) Move the TODOs

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

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 3106b7536b89..46d3e779bf5d 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -16,6 +16,12 @@ 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
+
+=cut
+
 # 18/01/2001 - 	Cleanups
 # 		Functions prototyped as foo(void) same as foo()
 # 		Stop eval'ing where we don't need to.
-- 
2.30.2

Re: [PATCH v3 01/15] scripts: kernel-doc: Add the NAME section

[Jonathan Corbet]

My first comment is that the changelogs need work.  A changelog on a
patch should say what *that patch* is doing and, more importantly, why.  
Neither of those are present here.

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

This information, to the extent that it's needed, should be a part of
the series description in part 0.

> You can see the POD with:
>
> $ perldoc scripts/kernel-doc
>
> * Transform documentation into POD (1/15)
> = Series explanation =
>
> This series transforms the free-form general comments - mainly the usage
> instructions and the meta information - into the standard Perl
> documentation format. Some of the original text is reduced out.
>
> The transformation includes language, paragraphing and editorial
> corrections.
>
> The only change in the script execution flow is the replacement of the
> 'usage' function with the native core Perl 'pod2usage'.
>
> The TODO suggestion to write POD found in the script is ancient, thus
> I can't address its author with a "Suggested-by" tag.
>
> The process consists of 15 steps.
>
> 1) Add the NAME section
> 2) Add the SYNOPSIS section
> 3) Relink argument parsing error handling to pod2usage
>
> The following subseries is disfunctional before its last part.
>
> 4) Translate the DESCRIPTION section
> 5) Translate the "Output format selection" subsection of OPTIONS
> 6) Translate the "Output format selection modifier" subsection of OPTIONS
> 7) Translate the "Output selection" subsection of OPTIONS
> 8) Translate the "Output selection modifiers" subsection of OPTIONS
> 9) Translate the "Other parameters" subsection of OPTIONS
> 10) Replace the usage function
>
> Here the DESCRIPTION and OPTIONS subseries is finished. The -h and -help
> parameters are handled by POD now.
>
> 11) Remove the "format of comments" comment block
> 12) Archive the pre-git museum
> 13) License cleanup
> 14) Refresh the copyright lines
> 15) Move the TODOs
>
> Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
> ---
>  scripts/kernel-doc | 6 ++++++
>  1 file changed, 6 insertions(+)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 3106b7536b89..46d3e779bf5d 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -16,6 +16,12 @@ 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
> +
> +=cut
> +

So, we do like patches to be granular and do only one thing, but this
may be taking it a bit too far.  It could well be combined with patch 2,
for example, which is just adding another section.

Meanwhile, I'd describe its role is something like "extract and format
documentation from the kernel source".

Thanks,

jon

[PATCH v3 02/15] scripts: kernel-doc: Add the SYNOPSIS section

[Tomasz Warniełło]

Rst-only options are grouped around rst, the rest is arranged
as in the OPTIONS susections (yet to be translated into POD,
check at the end of the series).

* Transform documentation into POD (2/15)
See step 1 for the series details.

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

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 46d3e779bf5d..c8fbf1d3d5aa 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -20,6 +20,25 @@ use strict;
 
 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
-- 
2.30.2

Re: [PATCH v3 02/15] scripts: kernel-doc: Add the SYNOPSIS section

[Jonathan Corbet]

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

> Rst-only options are grouped around rst, the rest is arranged
> as in the OPTIONS susections (yet to be translated into POD,
> check at the end of the series).

Again: *what* does *this* patch do, and *why*?  The above isn't be all
that illuminating to most readers.

> * Transform documentation into POD (2/15)
> See step 1 for the series details.

Don't put this kind of stuff into your changelogs, please.

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

Thanks,

jon

[PATCH v3 03/15] scripts: kernel-doc: Relink argument parsing error handling to pod2usage

[Tomasz Warniełło]

The former usage function is substituted, although not as the -h and -help
parameter handler yet.

* Transform documentation into POD (3/15)
See step 1 for the series details.

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

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index c8fbf1d3d5aa..c37fd36860f3 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,
+		);
     }
 }
 
-- 
2.30.2

Re: [PATCH v3 03/15] scripts: kernel-doc: Relink argument parsing error handling to pod2usage

[Jonathan Corbet]

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

> The former usage function is substituted, although not as the -h and -help
> parameter handler yet.
>
> * Transform documentation into POD (3/15)
> See step 1 for the series details.

Again, this doesn't belong here; I'll not mention it for the following
patches. 

> Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
> ---
>  scripts/kernel-doc | 20 +++++++++++++++++---
>  1 file changed, 17 insertions(+), 3 deletions(-)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index c8fbf1d3d5aa..c37fd36860f3 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,
> +		);

So you were asked before to retain the existing style, including
indentations.

Thanks,

jon

[PATCH v3 04/15] scripts: kernel-doc: Translate the DESCRIPTION section

[Tomasz Warniełło]

Notes:
- an article addition
- paragraphing correction

* Transform documentation into POD (4/15)
See step 1 for the series details.

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

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index c37fd36860f3..4d0b38c82bfb 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.
-- 
2.30.2

[PATCH v3 05/15] scripts: kernel-doc: Translate the "Output format selection" subsection of OPTIONS

[Tomasz Warniełło]

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.

* Transform documentation into POD (5/15)
See step 1 for the series details.

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

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 4d0b38c82bfb..8213399fd7ec 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
-- 
2.30.2

[PATCH v3 06/15] scripts: kernel-doc: Translate the "Output format selection modifier" subsection of OPTIONS

[Tomasz Warniełło]

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

* Transform documentation into POD (6/15)
See step 1 for the series details.

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

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 8213399fd7ec..f26966dd8bde 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
-- 
2.30.2

[PATCH v3 07/15] scripts: kernel-doc: Translate the "Output selection" subsection of OPTIONS

[Tomasz Warniełło]

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

* Transform documentation into POD (7/15)
See step 1 for the series details.

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

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index f26966dd8bde..629ba514db5d 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
-- 
2.30.2

[PATCH v3 08/15] scripts: kernel-doc: Translate the "Output selection modifiers" subsection of OPTIONS

[Tomasz Warniełło]

A subsection "reStructuredText only" is added for -enable-lineno.

Other notes:
- paragraphing correction

* Transform documentation into POD (8/15)
See step 1 for the series details.

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

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 629ba514db5d..c46d4b9afef2 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
-- 
2.30.2

[PATCH v3 09/15] scripts: kernel-doc: Translate the "Other parameters" subsection of OPTIONS

[Tomasz Warniełło]

Notes:
- The -help token is added.
- The entries are sorted alphbetically.

* Transform documentation into POD (9/15)
See step 1 for the series details.

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

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index c46d4b9afef2..33e7923683a0 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
-- 
2.30.2

[PATCH v3 10/15] scripts: kernel-doc: Replace the usage function

[Tomasz Warniełło]

This ends the fundamental POD transformation.

You can see the results with:

$ scripts/kernel-doc -help

* Transform documentation into POD (10/15)
See step 1 for the series details.

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

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 33e7923683a0..b4852c2ba243 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 <mail@danrl.de>
 
-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') {
-- 
2.30.2

[PATCH v3 11/15] scripts: kernel-doc: Remove the "format of comments" comment block

[Tomasz Warniełło]

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.

* Transform documentation into POD (11/15)
See step 1 for the series details.

= Meta note =

I guess, I should use the Suggested-by tag for credits.
Maintainers, please correct this if I'm doing this wrong.

Suggested-by: Jani Nikula <jani.nikula@linux.intel.com>
Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
---
 scripts/kernel-doc | 115 ---------------------------------------------
 1 file changed, 115 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index b4852c2ba243..493c024744b0 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -79,121 +79,6 @@ See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
 # 25/07/2012 - Added support for HTML5
 # -- Dan Luedtke <mail@danrl.de>
 
-#
-# 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;
-- 
2.30.2

Re: [PATCH v3 11/15] scripts: kernel-doc: Remove the "format of comments" comment block

[Jonathan Corbet]

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

> 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.

This is a relatively good *why* section - the sort of text all of the
patches should have.

> * Transform documentation into POD (11/15)
> See step 1 for the series details.
>
> = Meta note =
>
> I guess, I should use the Suggested-by tag for credits.
> Maintainers, please correct this if I'm doing this wrong.

"meta notes" can appear below the "---" line, that way the maintainer
doesn't have to edit them out when the patch is applied.

> Suggested-by: Jani Nikula <jani.nikula@linux.intel.com>
> Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
> ---
>  scripts/kernel-doc | 115 ---------------------------------------------
>  1 file changed, 115 deletions(-)

Thanks,

jon

[PATCH v3 12/15] scripts: kernel-doc: Archive the pre-git museum

[Tomasz Warniełło]

Jonathan Corbet suggested in a reply to my version 1, that these records
can go, since that's what the git log is for. I don't agree.

The log begins at 1da177e4c3f41524e886b7f1b8a0c1fc7321cac2. That's from
2005. One of those entries is indeed logged, so kudos for having me check
this. But not the older ones. Of course they can be found indirectly,
but then...

Why not just let them embellish the script tail?

As you can see, they don't even require any formatting there.

Are you sure you don't want them?

* Transform documentation into POD (12/15)
See step 1 for the series details.

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

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 493c024744b0..0be723f6e3a2 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -54,31 +54,10 @@ 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 <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>
-
 ## init lots of data
 
 my $errors = 0;
@@ -2518,3 +2497,25 @@ Treat warnings as errors.
 =back
 
 =cut
+
+PRE-GIT MUSEUM
+
+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>
-- 
2.30.2

Re: [PATCH v3 12/15] scripts: kernel-doc: Archive the pre-git museum

[Jonathan Corbet]

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

> Jonathan Corbet suggested in a reply to my version 1, that these records
> can go, since that's what the git log is for. I don't agree.
>
> The log begins at 1da177e4c3f41524e886b7f1b8a0c1fc7321cac2. That's from
> 2005. One of those entries is indeed logged, so kudos for having me check
> this. But not the older ones. Of course they can be found indirectly,
> but then...
>
> Why not just let them embellish the script tail?
>
> As you can see, they don't even require any formatting there.
>
> Are you sure you don't want them?

Do you really want this kind of stuff in the patch changelog for all
time?

Yes, I still believe that this information can go.  Why preserve a tiny
subset of a few small changes from over 20 years ago?  Just take it out,
please. 

> * Transform documentation into POD (12/15)
> See step 1 for the series details.
>
> Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
> ---
>  scripts/kernel-doc | 43 ++++++++++++++++++++++---------------------
>  1 file changed, 22 insertions(+), 21 deletions(-)

Thanks,

jon

[PATCH v3 13/15] scripts: kernel-doc: License cleanup

[Tomasz Warniełło]

As stated by Jonathan Corbet in the reply to my version 1, the SPDX line is
enough.

* Transform documentation into POD (13/15)
See step 1 for the series details.

(Still not sure about this tag line, so please correct if needed.)

Suggested-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
---
 scripts/kernel-doc | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 0be723f6e3a2..e4de593dbcb7 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -12,9 +12,6 @@ use strict;
 ## 								 ##
 ## #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             ##
 
 use Pod::Usage qw/pod2usage/;
 
-- 
2.30.2

[PATCH v3 14/15] scripts: kernel-doc: Refresh the copyright lines

[Tomasz Warniełło]

I'm not sure, why these notices need to stay at the top, but that's what
Jonathat Corbet replied to my version 1.

Anyways, I've cleaned them up a little. Looks good?

My name's included as the refreshing force of this venerable script.

* Transform documentation into POD (14/15)
See step 1 for the series details.

(Still not sure about this tag line, so please correct, let me know, etc.)

Suggested-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
---
 scripts/kernel-doc | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index e4de593dbcb7..dd5801cad519 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -4,14 +4,16 @@
 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.			 ##
+# 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.
+#
+# Copyright (C) 2022 Tomasz Warniełło (POD)
 
 use Pod::Usage qw/pod2usage/;
 
-- 
2.30.2

Re: [PATCH v3 14/15] scripts: kernel-doc: Refresh the copyright lines

[Jonathan Corbet]

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

> I'm not sure, why these notices need to stay at the top, but that's what
> Jonathat Corbet replied to my version 1.

Because that's how we do things with kernel code.

> Anyways, I've cleaned them up a little. Looks good?
>
> My name's included as the refreshing force of this venerable script.

Not sure if the text movement done so far crosses the bar where
copyright can be asserted or not...but I doubt anybody cares enough to
fight you on it :)

> * Transform documentation into POD (14/15)
> See step 1 for the series details.
>
> (Still not sure about this tag line, so please correct, let me know, etc.)
>
> Suggested-by: Jonathan Corbet <corbet@lwn.net>

Responding to review comments doesn't normally require a tag like this
unless the comment led to something new and significantly different.  I
don't think it's needed here.  What you can do is note that you've
responded to the comment below the "---" line.

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

Thanks,

jon

[PATCH v3 15/15] scripts: kernel-doc: Move the TODOs

[Tomasz Warniełło]

Earlier I thought I could take "add perldoc documentation" off
of this list. Now I think it also means a self-documentation.
And this is not even started.

I'm putting this block by the end, where it can quietly evolve.

* Transform documentation into POD (15/15)
See step 1 for the series details.

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

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index dd5801cad519..b9f381f0fc1b 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -53,10 +53,6 @@ See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
 
 # more perldoc at the end of the file
 
-# Still to do:
-# 	- add perldoc documentation
-# 	- Look more closely at some of the scarier bits :)
-
 ## init lots of data
 
 my $errors = 0;
@@ -2497,6 +2493,11 @@ Treat warnings as errors.
 
 =cut
 
+TODO
+
+- add perldoc documentation
+- Look more closely at some of the scarier bits :)
+
 PRE-GIT MUSEUM
 
 Original formatting preserved for its historical value.
-- 
2.30.2

Re: [PATCH v3 15/15] scripts: kernel-doc: Move the TODOs

[Jonathan Corbet]

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

> Earlier I thought I could take "add perldoc documentation" off
> of this list. Now I think it also means a self-documentation.
> And this is not even started.
>
> I'm putting this block by the end, where it can quietly evolve.
>
> * Transform documentation into POD (15/15)
> See step 1 for the series details.
>
> Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
> ---
>  scripts/kernel-doc | 9 +++++----
>  1 file changed, 5 insertions(+), 4 deletions(-)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index dd5801cad519..b9f381f0fc1b 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -53,10 +53,6 @@ See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
>  
>  # more perldoc at the end of the file
>  
> -# Still to do:
> -# 	- add perldoc documentation
> -# 	- Look more closely at some of the scarier bits :)
> -
>  ## init lots of data
>  
>  my $errors = 0;
> @@ -2497,6 +2493,11 @@ Treat warnings as errors.
>  
>  =cut
>  
> +TODO
> +
> +- add perldoc documentation
> +- Look more closely at some of the scarier bits :)
> +

I'm not convinced that there's any value in this bit of text, I'd just
take it out.

Thanks,

jon

Re: [PATCH v3 00/15] Transform documentation into POD

[Tomasz Warniełło]

Any news here?

Re: [PATCH v3 00/15] Transform documentation into POD

[Jonathan Corbet]

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

> Any news here?

Merge window is open; I'll look more closely at stuff like this toward
the end.

Thanks,

jon

Re: [PATCH v3 00/15] Transform documentation into POD

[Jonathan Corbet]

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

> This series transforms the free-form general comments - mainly the usage
> instructions and the meta information - into the standard Perl
> documentation format. Some of the original text is reduced out.
>
> The transformation includes language, paragraphing and editorial
> corrections.

OK, so I'm finally getting back to these, apologies again for the
unreasonable delay.  I do think that the work to this point is
worthwhile, and we should be able to get it in for 5.18.  I will have a
number of comments on the individual patches, though.

Thanks,

jon