scripts: kernel-doc: Transform documentation into POD (1/15)
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
@@ -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
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
@@ -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
PATCH v2 3/15 scripts: kernel-doc: Transform documentation into POD (3/15)
In reply to Tomasz WarniełłoStep 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
@@ -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
PATCH v2 4/15 scripts: kernel-doc: Transform documentation into POD (4/15)
In reply to Tomasz WarniełłoStep 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
@@ -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
PATCH v2 5/15 scripts: kernel-doc: Transform documentation into POD (5/15)
In reply to Tomasz WarniełłoStep 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
@@ -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