scripts: kernel-doc: Add the basic POD sections

The NAME section provides the doc title, while SYNOPSIS contains
the basic syntax and usage description, which will be printed
in the help document and in the error output produced on wrong script
usage.

The rationale is to give users simple and succinct enlightment,
at the same time structuring the script internally for the maintainers.

In the synopsis, Rst-only options are grouped around rst, and the rest is
arranged as in the OPTIONS subsections (yet to be translated into POD,
check at the end of the series).

The third of the basic sections, DESCRIPTION, is added separately.

Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Disliked-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/20220218181628.1411551-2-tomasz.warniello@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Tomasz Warniełło 2022-02-18 19:16:18 +01:00 committed by Jonathan Corbet
parent 62a40dad57
commit a5cdaea525

View File

@ -16,6 +16,31 @@ 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
=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
# Functions prototyped as foo(void) same as foo()
# Stop eval'ing where we don't need to.