Skip to contentSkip to conversation

scripts: kernel-doc: Transform documentation into POD (1/15)

PATCH New Tomasz Warniełło 1 participant 5 messages Jan 3, 2022 Documentation

lore
Share & tools
lore
#0 lore raw

PATCH v2 1/15 scripts: kernel-doc: Transform documentation into POD (1/15)

Step 1) Add the NAME section

You can see the POD with:

$ perldoc scripts/kernel-doc

= 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

---
 scripts/kernel-doc | 6 ++++++
 1 file changed, 6 insertions(+)
scripts/kernel-doc +6 -0
index 3106b7536b89..46d3e779bf5d 100755
@@ -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.

base-commit: 2a987e65025e2b79c6d453b78cb5985ac6e5eb26

Signature · 1 line
2.30.2
#1 lore raw

PATCH v2 2/15 scripts: kernel-doc: Transform documentation into POD (2/15)

Step 2) Add the SYNOPSIS section

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

See step 1 for the series details.

---
 scripts/kernel-doc | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
scripts/kernel-doc +19 -0
index 46d3e779bf5d..c8fbf1d3d5aa 100755
@@ -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
Signature · 1 line
2.30.2
#2 lore raw

PATCH v2 3/15 scripts: kernel-doc: Transform documentation into POD (3/15)

In reply to Tomasz Warniełło

Step 3) Relink argument parsing error handling to pod2usage

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

See step 1 for the series details.

---
 scripts/kernel-doc | 20 +++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)
scripts/kernel-doc +17 -3
index c8fbf1d3d5aa..9be526073b75 100755
@@ -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,
+			);
     }
 }
 
Signature · 1 line
2.30.2
#3 lore raw

PATCH v2 4/15 scripts: kernel-doc: Transform documentation into POD (4/15)

In reply to Tomasz Warniełło

Step 4) Translate the DESCRIPTION section

Notes:
- an article addition
- paragraphing correction

See step 1 for the series details.

---
 scripts/kernel-doc | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)
scripts/kernel-doc +9 -6
index 9be526073b75..c58c812c74cb 100755
@@ -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.
Signature · 1 line
2.30.2
#4 lore raw

PATCH v2 5/15 scripts: kernel-doc: Transform documentation into POD (5/15)

In reply to Tomasz Warniełło

Step 5) Translate the "Output format selection" subsection of OPTIONS

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.

See step 1 for the series details.

---
 scripts/kernel-doc | 31 ++++++++++++++++++++++++++-----
 1 file changed, 26 insertions(+), 5 deletions(-)
scripts/kernel-doc +26 -5
index c58c812c74cb..896c4775102d 100755
@@ -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
Signature · 1 line
2.30.2