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
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 <[email protected]>
---
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
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 <[email protected]>
---
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
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 <[email protected]>
---
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
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 <[email protected]>
---
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
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 <[email protected]>
---
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
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 <[email protected]>
---
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
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 <[email protected]>
---
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
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 <[email protected]>
---
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
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 <[email protected]>
---
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
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 <[email protected]>
---
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 <[email protected]>
-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
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 <[email protected]>
Signed-off-by: Tomasz Warniełło <[email protected]>
---
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 <[email protected]> ##
## 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
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 <[email protected]>
---
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.
-# -- [email protected]
-
-# 27/06/2001 - Allowed whitespace after initial "/**" and
-# allowed comments before function declarations.
-# -- Christian Kreibich <[email protected]>
-
# 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 <[email protected]>
-
-# 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 <[email protected]>
-
-# 25/07/2012 - Added support for HTML5
-# -- Dan Luedtke <[email protected]>
-
## 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.
+# -- [email protected]
+
+# 27/06/2001 - Allowed whitespace after initial "/**" and
+# allowed comments before function declarations.
+# -- Christian Kreibich <[email protected]>
+
+# 26/05/2001 - Support for separate source and object trees.
+# Return error code.
+# Keith Owens <[email protected]>
+
+# 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 <[email protected]>
--
2.30.2
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 <[email protected]>
Signed-off-by: Tomasz Warniełło <[email protected]>
---
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 <[email protected]> ##
-## Copyright (C) 2001 Simon Huggins ##
-## Copyright (C) 2005-2012 Randy Dunlap ##
-## Copyright (C) 2012 Dan Luedtke ##
-## ##
-## #define enhancements by Armin Kuster <[email protected]> ##
-## Copyright (c) 2000 MontaVista Software, Inc. ##
+# Copyright (C) 1998 Michael Zucchi, All Rights Reserved
+# Copyright (C) 2000, 1 Tim Waugh <[email protected]>
+# Copyright (C) 2001 Simon Huggins
+# Copyright (C) 2005-2012 Randy Dunlap
+# Copyright (C) 2012 Dan Luedtke
+#
+# #define enhancements by Armin Kuster <[email protected]>
+# Copyright (C) 2000 MontaVista Software, Inc.
+#
+# Copyright (C) 2022 Tomasz Warniełło (POD)
use Pod::Usage qw/pod2usage/;
--
2.30.2
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 <[email protected]>
---
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
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 <[email protected]>
Signed-off-by: Tomasz Warniełło <[email protected]>
---
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 <[email protected]>
-#
-# 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
Tomasz Warniełło <[email protected]> writes:
> Any news here?
Merge window is open; I'll look more closely at stuff like this toward
the end.
Thanks,
jon
Tomasz Warniełło <[email protected]> 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 <[email protected]>
> ---
> scripts/kernel-doc | 43 ++++++++++++++++++++++---------------------
> 1 file changed, 22 insertions(+), 21 deletions(-)
Thanks,
jon
Tomasz Warniełło <[email protected]> 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 <[email protected]>
> ---
> scripts/kernel-doc | 19 +++++++++++++++++++
> 1 file changed, 19 insertions(+)
Thanks,
jon
Tomasz Warniełło <[email protected]> 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
Tomasz Warniełło <[email protected]> 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 <[email protected]>
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 <[email protected]>
> ---
> scripts/kernel-doc | 18 ++++++++++--------
> 1 file changed, 10 insertions(+), 8 deletions(-)
Thanks,
jon
Tomasz Warniełło <[email protected]> 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 <[email protected]>
> ---
> 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
Tomasz Warniełło <[email protected]> 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 <[email protected]>
> ---
> 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
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 <[email protected]> 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 <[email protected]>
> ---
> 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
Tomasz Warniełło <[email protected]> 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 <[email protected]>
> Signed-off-by: Tomasz Warniełło <[email protected]>
> ---
> scripts/kernel-doc | 115 ---------------------------------------------
> 1 file changed, 115 deletions(-)
Thanks,
jon