scripts: kernel-doc: Transform documentation into POD (6/15)
PATCH v2 6/15 scripts: kernel-doc: Transform documentation into POD (6/15)
Step 6) Translate the "Output format selection modifier" subsection
of OPTIONS
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
See step 1 for the series details.
--- scripts/kernel-doc | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-)
scripts/kernel-doc +15 -7
@@ -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
Signature · 1 line
2.30.2
PATCH v2 7/15 scripts: kernel-doc: Transform documentation into POD (7/15)
Step 7) Translate the "Output selection" subsection of OPTIONS
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
See step 1 for the series details.
--- scripts/kernel-doc | 42 +++++++++++++++++++++++++++++------------- 1 file changed, 29 insertions(+), 13 deletions(-)
scripts/kernel-doc +29 -13
@@ -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
Signature · 1 line
2.30.2
PATCH v2 8/15 scripts: kernel-doc: Transform documentation into POD (8/15)
In reply to Tomasz WarniełłoStep 8) Translate the "Output selection modifiers" subsection of OPTIONS
A subsection "reStructuredText only" is added for -enable-lineno.
Other notes:
- paragraphing correction
See step 1 for the series details.
--- scripts/kernel-doc | 37 +++++++++++++++++++++++++++++-------- 1 file changed, 29 insertions(+), 8 deletions(-)
scripts/kernel-doc +29 -8
@@ -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
Signature · 1 line
2.30.2
PATCH v2 9/15 scripts: kernel-doc: Transform documentation into POD (9/15)
In reply to Tomasz WarniełłoStep 9) Translate the "Other parameters" subsection of OPTIONS
Notes:
- The -help token is added.
- The entries are sorted alphbetically.
See step 1 for the series details.
--- scripts/kernel-doc | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-)
scripts/kernel-doc +18 -5
@@ -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
Signature · 1 line
2.30.2
PATCH v2 10/15 scripts: kernel-doc: Transform documentation into POD (10/15)
In reply to Tomasz WarniełłoStep 10) Replace the usage function
This ends the fundamental POD transformation.
You can see the results with:
$ scripts/kernel-doc -help
See step 1 for the series details.
--- scripts/kernel-doc | 11 +---------- 1 file changed, 1 insertion(+), 10 deletions(-)
scripts/kernel-doc +1 -10
@@ -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') {
Signature · 1 line
2.30.2