linux-doc.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* [PATCH v3 00/15] Transform documentation into POD
@ 2022-01-04  1:59 Tomasz Warniełło
  2022-01-04  1:59 ` [PATCH v3 01/15] scripts: kernel-doc: Add the NAME section Tomasz Warniełło
                   ` (16 more replies)
  0 siblings, 17 replies; 26+ messages in thread
From: Tomasz Warniełło @ 2022-01-04  1:59 UTC (permalink / raw)
  To: corbet; +Cc: Tomasz Warniełło, linux-doc, linux-kernel

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


^ permalink raw reply	[flat|nested] 26+ messages in thread

* [PATCH v3 01/15] scripts: kernel-doc: Add the NAME section
  2022-01-04  1:59 [PATCH v3 00/15] Transform documentation into POD Tomasz Warniełło
@ 2022-01-04  1:59 ` Tomasz Warniełło
  2022-02-16 23:18   ` Jonathan Corbet
  2022-01-04  1:59 ` [PATCH v3 02/15] scripts: kernel-doc: Add the SYNOPSIS section Tomasz Warniełło
                   ` (15 subsequent siblings)
  16 siblings, 1 reply; 26+ messages in thread
From: Tomasz Warniełło @ 2022-01-04  1:59 UTC (permalink / raw)
  To: corbet; +Cc: Tomasz Warniełło, linux-doc, linux-kernel

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


^ permalink raw reply related	[flat|nested] 26+ messages in thread

* [PATCH v3 02/15] scripts: kernel-doc: Add the SYNOPSIS section
  2022-01-04  1:59 [PATCH v3 00/15] Transform documentation into POD Tomasz Warniełło
  2022-01-04  1:59 ` [PATCH v3 01/15] scripts: kernel-doc: Add the NAME section Tomasz Warniełło
@ 2022-01-04  1:59 ` Tomasz Warniełło
  2022-02-16 23:19   ` Jonathan Corbet
  2022-01-04  1:59 ` [PATCH v3 03/15] scripts: kernel-doc: Relink argument parsing error handling to pod2usage Tomasz Warniełło
                   ` (14 subsequent siblings)
  16 siblings, 1 reply; 26+ messages in thread
From: Tomasz Warniełło @ 2022-01-04  1:59 UTC (permalink / raw)
  To: corbet; +Cc: Tomasz Warniełło, linux-doc, linux-kernel

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


^ permalink raw reply related	[flat|nested] 26+ messages in thread

* [PATCH v3 03/15] scripts: kernel-doc: Relink argument parsing error handling to pod2usage
  2022-01-04  1:59 [PATCH v3 00/15] Transform documentation into POD Tomasz Warniełło
  2022-01-04  1:59 ` [PATCH v3 01/15] scripts: kernel-doc: Add the NAME section Tomasz Warniełło
  2022-01-04  1:59 ` [PATCH v3 02/15] scripts: kernel-doc: Add the SYNOPSIS section Tomasz Warniełło
@ 2022-01-04  1:59 ` Tomasz Warniełło
  2022-02-16 23:21   ` Jonathan Corbet
  2022-01-04  1:59 ` [PATCH v3 04/15] scripts: kernel-doc: Translate the DESCRIPTION section Tomasz Warniełło
                   ` (13 subsequent siblings)
  16 siblings, 1 reply; 26+ messages in thread
From: Tomasz Warniełło @ 2022-01-04  1:59 UTC (permalink / raw)
  To: corbet; +Cc: Tomasz Warniełło, linux-doc, linux-kernel

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


^ permalink raw reply related	[flat|nested] 26+ messages in thread

* [PATCH v3 04/15] scripts: kernel-doc: Translate the DESCRIPTION section
  2022-01-04  1:59 [PATCH v3 00/15] Transform documentation into POD Tomasz Warniełło
                   ` (2 preceding siblings ...)
  2022-01-04  1:59 ` [PATCH v3 03/15] scripts: kernel-doc: Relink argument parsing error handling to pod2usage Tomasz Warniełło
@ 2022-01-04  1:59 ` Tomasz Warniełło
  2022-01-04  1:59 ` [PATCH v3 05/15] scripts: kernel-doc: Translate the "Output format selection" subsection of OPTIONS Tomasz Warniełło
                   ` (12 subsequent siblings)
  16 siblings, 0 replies; 26+ messages in thread
From: Tomasz Warniełło @ 2022-01-04  1:59 UTC (permalink / raw)
  To: corbet; +Cc: Tomasz Warniełło, linux-doc, linux-kernel

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


^ permalink raw reply related	[flat|nested] 26+ messages in thread

* [PATCH v3 05/15] scripts: kernel-doc: Translate the "Output format selection" subsection of OPTIONS
  2022-01-04  1:59 [PATCH v3 00/15] Transform documentation into POD Tomasz Warniełło
                   ` (3 preceding siblings ...)
  2022-01-04  1:59 ` [PATCH v3 04/15] scripts: kernel-doc: Translate the DESCRIPTION section Tomasz Warniełło
@ 2022-01-04  1:59 ` Tomasz Warniełło
  2022-01-04  1:59 ` [PATCH v3 06/15] scripts: kernel-doc: Translate the "Output format selection modifier" " Tomasz Warniełło
                   ` (11 subsequent siblings)
  16 siblings, 0 replies; 26+ messages in thread
From: Tomasz Warniełło @ 2022-01-04  1:59 UTC (permalink / raw)
  To: corbet; +Cc: Tomasz Warniełło, linux-doc, linux-kernel

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


^ permalink raw reply related	[flat|nested] 26+ messages in thread

* [PATCH v3 06/15] scripts: kernel-doc: Translate the "Output format selection modifier" subsection of OPTIONS
  2022-01-04  1:59 [PATCH v3 00/15] Transform documentation into POD Tomasz Warniełło
                   ` (4 preceding siblings ...)
  2022-01-04  1:59 ` [PATCH v3 05/15] scripts: kernel-doc: Translate the "Output format selection" subsection of OPTIONS Tomasz Warniełło
@ 2022-01-04  1:59 ` Tomasz Warniełło
  2022-01-04  1:59 ` [PATCH v3 07/15] scripts: kernel-doc: Translate the "Output selection" " Tomasz Warniełło
                   ` (10 subsequent siblings)
  16 siblings, 0 replies; 26+ messages in thread
From: Tomasz Warniełło @ 2022-01-04  1:59 UTC (permalink / raw)
  To: corbet; +Cc: Tomasz Warniełło, linux-doc, linux-kernel

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


^ permalink raw reply related	[flat|nested] 26+ messages in thread

* [PATCH v3 07/15] scripts: kernel-doc: Translate the "Output selection" subsection of OPTIONS
  2022-01-04  1:59 [PATCH v3 00/15] Transform documentation into POD Tomasz Warniełło
                   ` (5 preceding siblings ...)
  2022-01-04  1:59 ` [PATCH v3 06/15] scripts: kernel-doc: Translate the "Output format selection modifier" " Tomasz Warniełło
@ 2022-01-04  1:59 ` Tomasz Warniełło
  2022-01-04  1:59 ` [PATCH v3 08/15] scripts: kernel-doc: Translate the "Output selection modifiers" " Tomasz Warniełło
                   ` (9 subsequent siblings)
  16 siblings, 0 replies; 26+ messages in thread
From: Tomasz Warniełło @ 2022-01-04  1:59 UTC (permalink / raw)
  To: corbet; +Cc: Tomasz Warniełło, linux-doc, linux-kernel

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


^ permalink raw reply related	[flat|nested] 26+ messages in thread

* [PATCH v3 08/15] scripts: kernel-doc: Translate the "Output selection modifiers" subsection of OPTIONS
  2022-01-04  1:59 [PATCH v3 00/15] Transform documentation into POD Tomasz Warniełło
                   ` (6 preceding siblings ...)
  2022-01-04  1:59 ` [PATCH v3 07/15] scripts: kernel-doc: Translate the "Output selection" " Tomasz Warniełło
@ 2022-01-04  1:59 ` Tomasz Warniełło
  2022-01-04  1:59 ` [PATCH v3 09/15] scripts: kernel-doc: Translate the "Other parameters" " Tomasz Warniełło
                   ` (8 subsequent siblings)
  16 siblings, 0 replies; 26+ messages in thread
From: Tomasz Warniełło @ 2022-01-04  1:59 UTC (permalink / raw)
  To: corbet; +Cc: Tomasz Warniełło, linux-doc, linux-kernel

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


^ permalink raw reply related	[flat|nested] 26+ messages in thread

* [PATCH v3 09/15] scripts: kernel-doc: Translate the "Other parameters" subsection of OPTIONS
  2022-01-04  1:59 [PATCH v3 00/15] Transform documentation into POD Tomasz Warniełło
                   ` (7 preceding siblings ...)
  2022-01-04  1:59 ` [PATCH v3 08/15] scripts: kernel-doc: Translate the "Output selection modifiers" " Tomasz Warniełło
@ 2022-01-04  1:59 ` Tomasz Warniełło
  2022-01-04  1:59 ` [PATCH v3 10/15] scripts: kernel-doc: Replace the usage function Tomasz Warniełło
                   ` (7 subsequent siblings)
  16 siblings, 0 replies; 26+ messages in thread
From: Tomasz Warniełło @ 2022-01-04  1:59 UTC (permalink / raw)
  To: corbet; +Cc: Tomasz Warniełło, linux-doc, linux-kernel

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


^ permalink raw reply related	[flat|nested] 26+ messages in thread

* [PATCH v3 10/15] scripts: kernel-doc: Replace the usage function
  2022-01-04  1:59 [PATCH v3 00/15] Transform documentation into POD Tomasz Warniełło
                   ` (8 preceding siblings ...)
  2022-01-04  1:59 ` [PATCH v3 09/15] scripts: kernel-doc: Translate the "Other parameters" " Tomasz Warniełło
@ 2022-01-04  1:59 ` Tomasz Warniełło
  2022-01-04  1:59 ` [PATCH v3 11/15] scripts: kernel-doc: Remove the "format of comments" comment block Tomasz Warniełło
                   ` (6 subsequent siblings)
  16 siblings, 0 replies; 26+ messages in thread
From: Tomasz Warniełło @ 2022-01-04  1:59 UTC (permalink / raw)
  To: corbet; +Cc: Tomasz Warniełło, linux-doc, linux-kernel

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


^ permalink raw reply related	[flat|nested] 26+ messages in thread

* [PATCH v3 11/15] scripts: kernel-doc: Remove the "format of comments" comment block
  2022-01-04  1:59 [PATCH v3 00/15] Transform documentation into POD Tomasz Warniełło
                   ` (9 preceding siblings ...)
  2022-01-04  1:59 ` [PATCH v3 10/15] scripts: kernel-doc: Replace the usage function Tomasz Warniełło
@ 2022-01-04  1:59 ` Tomasz Warniełło
  2022-02-16 23:26   ` Jonathan Corbet
  2022-01-04  1:59 ` [PATCH v3 12/15] scripts: kernel-doc: Archive the pre-git museum Tomasz Warniełło
                   ` (5 subsequent siblings)
  16 siblings, 1 reply; 26+ messages in thread
From: Tomasz Warniełło @ 2022-01-04  1:59 UTC (permalink / raw)
  To: corbet; +Cc: Tomasz Warniełło, linux-doc, linux-kernel, Jani Nikula

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


^ permalink raw reply related	[flat|nested] 26+ messages in thread

* [PATCH v3 12/15] scripts: kernel-doc: Archive the pre-git museum
  2022-01-04  1:59 [PATCH v3 00/15] Transform documentation into POD Tomasz Warniełło
                   ` (10 preceding siblings ...)
  2022-01-04  1:59 ` [PATCH v3 11/15] scripts: kernel-doc: Remove the "format of comments" comment block Tomasz Warniełło
@ 2022-01-04  1:59 ` Tomasz Warniełło
  2022-02-16 23:29   ` Jonathan Corbet
  2022-01-04  1:59 ` [PATCH v3 13/15] scripts: kernel-doc: License cleanup Tomasz Warniełło
                   ` (4 subsequent siblings)
  16 siblings, 1 reply; 26+ messages in thread
From: Tomasz Warniełło @ 2022-01-04  1:59 UTC (permalink / raw)
  To: corbet; +Cc: Tomasz Warniełło, linux-doc, linux-kernel

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


^ permalink raw reply related	[flat|nested] 26+ messages in thread

* [PATCH v3 13/15] scripts: kernel-doc: License cleanup
  2022-01-04  1:59 [PATCH v3 00/15] Transform documentation into POD Tomasz Warniełło
                   ` (11 preceding siblings ...)
  2022-01-04  1:59 ` [PATCH v3 12/15] scripts: kernel-doc: Archive the pre-git museum Tomasz Warniełło
@ 2022-01-04  1:59 ` Tomasz Warniełło
  2022-01-04  1:59 ` [PATCH v3 14/15] scripts: kernel-doc: Refresh the copyright lines Tomasz Warniełło
                   ` (3 subsequent siblings)
  16 siblings, 0 replies; 26+ messages in thread
From: Tomasz Warniełło @ 2022-01-04  1:59 UTC (permalink / raw)
  To: corbet; +Cc: Tomasz Warniełło, linux-doc, linux-kernel

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


^ permalink raw reply related	[flat|nested] 26+ messages in thread

* [PATCH v3 14/15] scripts: kernel-doc: Refresh the copyright lines
  2022-01-04  1:59 [PATCH v3 00/15] Transform documentation into POD Tomasz Warniełło
                   ` (12 preceding siblings ...)
  2022-01-04  1:59 ` [PATCH v3 13/15] scripts: kernel-doc: License cleanup Tomasz Warniełło
@ 2022-01-04  1:59 ` Tomasz Warniełło
  2022-02-16 23:34   ` Jonathan Corbet
  2022-01-04  1:59 ` [PATCH v3 15/15] scripts: kernel-doc: Move the TODOs Tomasz Warniełło
                   ` (2 subsequent siblings)
  16 siblings, 1 reply; 26+ messages in thread
From: Tomasz Warniełło @ 2022-01-04  1:59 UTC (permalink / raw)
  To: corbet; +Cc: Tomasz Warniełło, linux-doc, linux-kernel

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


^ permalink raw reply related	[flat|nested] 26+ messages in thread

* [PATCH v3 15/15] scripts: kernel-doc: Move the TODOs
  2022-01-04  1:59 [PATCH v3 00/15] Transform documentation into POD Tomasz Warniełło
                   ` (13 preceding siblings ...)
  2022-01-04  1:59 ` [PATCH v3 14/15] scripts: kernel-doc: Refresh the copyright lines Tomasz Warniełło
@ 2022-01-04  1:59 ` Tomasz Warniełło
  2022-02-16 23:34   ` Jonathan Corbet
  2022-01-13  6:41 ` [PATCH v3 00/15] Transform documentation into POD Tomasz Warniełło
  2022-02-16 23:14 ` Jonathan Corbet
  16 siblings, 1 reply; 26+ messages in thread
From: Tomasz Warniełło @ 2022-01-04  1:59 UTC (permalink / raw)
  To: corbet; +Cc: Tomasz Warniełło, linux-doc, linux-kernel

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


^ permalink raw reply related	[flat|nested] 26+ messages in thread

* Re: [PATCH v3 00/15] Transform documentation into POD
  2022-01-04  1:59 [PATCH v3 00/15] Transform documentation into POD Tomasz Warniełło
                   ` (14 preceding siblings ...)
  2022-01-04  1:59 ` [PATCH v3 15/15] scripts: kernel-doc: Move the TODOs Tomasz Warniełło
@ 2022-01-13  6:41 ` Tomasz Warniełło
  2022-01-13 16:19   ` Jonathan Corbet
  2022-02-16 23:14 ` Jonathan Corbet
  16 siblings, 1 reply; 26+ messages in thread
From: Tomasz Warniełło @ 2022-01-13  6:41 UTC (permalink / raw)
  To: corbet; +Cc: linux-doc, linux-kernel

Any news here?

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: [PATCH v3 00/15] Transform documentation into POD
  2022-01-13  6:41 ` [PATCH v3 00/15] Transform documentation into POD Tomasz Warniełło
@ 2022-01-13 16:19   ` Jonathan Corbet
  0 siblings, 0 replies; 26+ messages in thread
From: Jonathan Corbet @ 2022-01-13 16:19 UTC (permalink / raw)
  To: Tomasz Warniełło; +Cc: linux-doc, linux-kernel

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

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: [PATCH v3 00/15] Transform documentation into POD
  2022-01-04  1:59 [PATCH v3 00/15] Transform documentation into POD Tomasz Warniełło
                   ` (15 preceding siblings ...)
  2022-01-13  6:41 ` [PATCH v3 00/15] Transform documentation into POD Tomasz Warniełło
@ 2022-02-16 23:14 ` Jonathan Corbet
  16 siblings, 0 replies; 26+ messages in thread
From: Jonathan Corbet @ 2022-02-16 23:14 UTC (permalink / raw)
  To: Tomasz Warniełło
  Cc: Tomasz Warniełło, linux-doc, linux-kernel

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

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: [PATCH v3 01/15] scripts: kernel-doc: Add the NAME section
  2022-01-04  1:59 ` [PATCH v3 01/15] scripts: kernel-doc: Add the NAME section Tomasz Warniełło
@ 2022-02-16 23:18   ` Jonathan Corbet
  0 siblings, 0 replies; 26+ messages in thread
From: Jonathan Corbet @ 2022-02-16 23:18 UTC (permalink / raw)
  To: Tomasz Warniełło
  Cc: Tomasz Warniełło, linux-doc, linux-kernel

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

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: [PATCH v3 02/15] scripts: kernel-doc: Add the SYNOPSIS section
  2022-01-04  1:59 ` [PATCH v3 02/15] scripts: kernel-doc: Add the SYNOPSIS section Tomasz Warniełło
@ 2022-02-16 23:19   ` Jonathan Corbet
  0 siblings, 0 replies; 26+ messages in thread
From: Jonathan Corbet @ 2022-02-16 23:19 UTC (permalink / raw)
  To: Tomasz Warniełło
  Cc: Tomasz Warniełło, linux-doc, linux-kernel

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

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: [PATCH v3 03/15] scripts: kernel-doc: Relink argument parsing error handling to pod2usage
  2022-01-04  1:59 ` [PATCH v3 03/15] scripts: kernel-doc: Relink argument parsing error handling to pod2usage Tomasz Warniełło
@ 2022-02-16 23:21   ` Jonathan Corbet
  0 siblings, 0 replies; 26+ messages in thread
From: Jonathan Corbet @ 2022-02-16 23:21 UTC (permalink / raw)
  To: Tomasz Warniełło
  Cc: Tomasz Warniełło, linux-doc, linux-kernel

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

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: [PATCH v3 11/15] scripts: kernel-doc: Remove the "format of comments" comment block
  2022-01-04  1:59 ` [PATCH v3 11/15] scripts: kernel-doc: Remove the "format of comments" comment block Tomasz Warniełło
@ 2022-02-16 23:26   ` Jonathan Corbet
  0 siblings, 0 replies; 26+ messages in thread
From: Jonathan Corbet @ 2022-02-16 23:26 UTC (permalink / raw)
  To: Tomasz Warniełło
  Cc: Tomasz Warniełło, linux-doc, linux-kernel, Jani Nikula

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

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: [PATCH v3 12/15] scripts: kernel-doc: Archive the pre-git museum
  2022-01-04  1:59 ` [PATCH v3 12/15] scripts: kernel-doc: Archive the pre-git museum Tomasz Warniełło
@ 2022-02-16 23:29   ` Jonathan Corbet
  0 siblings, 0 replies; 26+ messages in thread
From: Jonathan Corbet @ 2022-02-16 23:29 UTC (permalink / raw)
  To: Tomasz Warniełło
  Cc: Tomasz Warniełło, linux-doc, linux-kernel

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

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: [PATCH v3 14/15] scripts: kernel-doc: Refresh the copyright lines
  2022-01-04  1:59 ` [PATCH v3 14/15] scripts: kernel-doc: Refresh the copyright lines Tomasz Warniełło
@ 2022-02-16 23:34   ` Jonathan Corbet
  0 siblings, 0 replies; 26+ messages in thread
From: Jonathan Corbet @ 2022-02-16 23:34 UTC (permalink / raw)
  To: Tomasz Warniełło
  Cc: Tomasz Warniełło, linux-doc, linux-kernel

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

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: [PATCH v3 15/15] scripts: kernel-doc: Move the TODOs
  2022-01-04  1:59 ` [PATCH v3 15/15] scripts: kernel-doc: Move the TODOs Tomasz Warniełło
@ 2022-02-16 23:34   ` Jonathan Corbet
  0 siblings, 0 replies; 26+ messages in thread
From: Jonathan Corbet @ 2022-02-16 23:34 UTC (permalink / raw)
  To: Tomasz Warniełło
  Cc: Tomasz Warniełło, linux-doc, linux-kernel

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

^ permalink raw reply	[flat|nested] 26+ messages in thread

end of thread, other threads:[~2022-02-16 23:34 UTC | newest]

Thread overview: 26+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-01-04  1:59 [PATCH v3 00/15] Transform documentation into POD Tomasz Warniełło
2022-01-04  1:59 ` [PATCH v3 01/15] scripts: kernel-doc: Add the NAME section Tomasz Warniełło
2022-02-16 23:18   ` Jonathan Corbet
2022-01-04  1:59 ` [PATCH v3 02/15] scripts: kernel-doc: Add the SYNOPSIS section Tomasz Warniełło
2022-02-16 23:19   ` Jonathan Corbet
2022-01-04  1:59 ` [PATCH v3 03/15] scripts: kernel-doc: Relink argument parsing error handling to pod2usage Tomasz Warniełło
2022-02-16 23:21   ` Jonathan Corbet
2022-01-04  1:59 ` [PATCH v3 04/15] scripts: kernel-doc: Translate the DESCRIPTION section Tomasz Warniełło
2022-01-04  1:59 ` [PATCH v3 05/15] scripts: kernel-doc: Translate the "Output format selection" subsection of OPTIONS Tomasz Warniełło
2022-01-04  1:59 ` [PATCH v3 06/15] scripts: kernel-doc: Translate the "Output format selection modifier" " Tomasz Warniełło
2022-01-04  1:59 ` [PATCH v3 07/15] scripts: kernel-doc: Translate the "Output selection" " Tomasz Warniełło
2022-01-04  1:59 ` [PATCH v3 08/15] scripts: kernel-doc: Translate the "Output selection modifiers" " Tomasz Warniełło
2022-01-04  1:59 ` [PATCH v3 09/15] scripts: kernel-doc: Translate the "Other parameters" " Tomasz Warniełło
2022-01-04  1:59 ` [PATCH v3 10/15] scripts: kernel-doc: Replace the usage function Tomasz Warniełło
2022-01-04  1:59 ` [PATCH v3 11/15] scripts: kernel-doc: Remove the "format of comments" comment block Tomasz Warniełło
2022-02-16 23:26   ` Jonathan Corbet
2022-01-04  1:59 ` [PATCH v3 12/15] scripts: kernel-doc: Archive the pre-git museum Tomasz Warniełło
2022-02-16 23:29   ` Jonathan Corbet
2022-01-04  1:59 ` [PATCH v3 13/15] scripts: kernel-doc: License cleanup Tomasz Warniełło
2022-01-04  1:59 ` [PATCH v3 14/15] scripts: kernel-doc: Refresh the copyright lines Tomasz Warniełło
2022-02-16 23:34   ` Jonathan Corbet
2022-01-04  1:59 ` [PATCH v3 15/15] scripts: kernel-doc: Move the TODOs Tomasz Warniełło
2022-02-16 23:34   ` Jonathan Corbet
2022-01-13  6:41 ` [PATCH v3 00/15] Transform documentation into POD Tomasz Warniełło
2022-01-13 16:19   ` Jonathan Corbet
2022-02-16 23:14 ` Jonathan Corbet

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).