linux-toradex.git/scripts/kernel-doc, branch v5.19-rc1

scripts/kernel-doc: change the line number meta info

2022-03-28T19:53:46+00:00

In order to make it more standard and ReST compatible,
change the meta-tag used with --enable-lineno from:

        #define LINENO

to
        .. LINENO

In practice, no	functional changes.

Signed-off-by: Mauro Carvalho Chehab 
Link: https://lore.kernel.org/r/40725032b5a4a33db740bf1de397523af958ff8a.1648290305.git.mchehab@kernel.org
Signed-off-by: Jonathan Corbet

docs: scripts/kernel-doc: Detect absence of FILE arg

2022-02-24T19:13:19+00:00

Currently, when there is no FILE argument following a switch such
as -man, -rst, or -none, kernel-doc exits with a warning from perl
(long msg folded):

    Use of uninitialized value $ARGV[0] in pattern match (m//)
    at ./scripts/kernel-doc line 438.

, which is unhelpful.

Improve the behavior by adding a check at the bottom of parsing
loop.
If the argument is absent, display help text and exit with
the code of 1 (via usage()).

Signed-off-by: Akira Yokosawa 
Cc: Randy Dunlap 
Link: https://lore.kernel.org/r/7b136049-a3ba-0eb5-8717-364d773ff914@gmail.com
[jc: reworked to fix conflict with pod patches]
Signed-off-by: Jonathan Corbet

scripts: kernel-doc: Refresh the copyright lines

2022-02-24T17:52:47+00:00

I wanted to clean up these lines, but in the end decided not to touch
the old ones and just add my own about POD. I'll leave the cleanup
for lawyers.

Signed-off-by: Tomasz Warniełło 
Tested-by: Randy Dunlap 
Acked-by: Randy Dunlap 
Disliked-by: Akira Yokosawa 
Link: https://lore.kernel.org/r/20220218181628.1411551-12-tomasz.warniello@gmail.com
Signed-off-by: Jonathan Corbet

scripts: kernel-doc: Drop obsolete comments

2022-02-24T17:52:47+00:00

What for? To improve the script maintainability.

1. License

As stated by Jonathan Corbet in the reply to my version 1, the SPDX line
is enough.

2. The to-do list comment

As suggested by Jonathan Corbet in reply to my version 3, this section
doesn't need to be transitioned. And so it is removed for clarity.

3. The historical changelog comments

As suggested by Jonathan Corbet in a reply to v3, this section can go.
I wanted to keep it, but since it doesn't contain copyright notices,
let's just have it clean and simple.

4. The "format of comments" comment block

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.

Suggested-by: Jonathan Corbet 
Suggested-by: Jani Nikula 
Signed-off-by: Tomasz Warniełło 
Tested-by: Randy Dunlap 
Acked-by: Randy Dunlap 
Disliked-by: Akira Yokosawa 
Link: https://lore.kernel.org/r/20220218181628.1411551-11-tomasz.warniello@gmail.com
Signed-off-by: Jonathan Corbet

scripts: kernel-doc: Replace the usage function

2022-02-24T17:52:46+00:00

Aim: unified POD, user more satisfied, script better structured

You can see the results with:

$ scripts/kernel-doc -help

Signed-off-by: Tomasz Warniełło 
Tested-by: Randy Dunlap 
Acked-by: Randy Dunlap 
Disliked-by: Akira Yokosawa 
Link: https://lore.kernel.org/r/20220218181628.1411551-10-tomasz.warniello@gmail.com
Signed-off-by: Jonathan Corbet

scripts: kernel-doc: Translate the "Other parameters" subsection of OPTIONS

2022-02-24T17:52:46+00:00

Aim: unified POD, user more satisfied, script better structured

Notes:
- The -help token is added.
- The entries are sorted alphbetically.

Signed-off-by: Tomasz Warniełło 
Tested-by: Randy Dunlap 
Acked-by: Randy Dunlap 
Disliked-by: Akira Yokosawa 
Link: https://lore.kernel.org/r/20220218181628.1411551-9-tomasz.warniello@gmail.com
Signed-off-by: Jonathan Corbet

scripts: kernel-doc: Translate the "Output selection modifiers" subsection of OPTIONS

2022-02-24T17:52:46+00:00

Aim: unified POD, user more satisfied, script better structured

A subsection "reStructuredText only" is added for -enable-lineno.

Other notes:
- paragraphing correction

Signed-off-by: Tomasz Warniełło 
Tested-by: Randy Dunlap 
Acked-by: Randy Dunlap 
Disliked-by: Akira Yokosawa 
Link: https://lore.kernel.org/r/20220218181628.1411551-8-tomasz.warniello@gmail.com
Signed-off-by: Jonathan Corbet

scripts: kernel-doc: Translate the "Output selection" subsection of OPTIONS

2022-02-24T17:52:46+00:00

Aim: unified POD, user more satisfied, script better structured

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

Signed-off-by: Tomasz Warniełło 
Tested-by: Randy Dunlap 
Acked-by: Randy Dunlap 
Disliked-by: Akira Yokosawa 
Link: https://lore.kernel.org/r/20220218181628.1411551-7-tomasz.warniello@gmail.com
Signed-off-by: Jonathan Corbet

scripts: kernel-doc: Translate the "Output format selection modifier" subsection of OPTIONS

2022-02-24T17:52:46+00:00

Aim: unified POD, user more happy

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

Signed-off-by: Tomasz Warniełło 
Tested-by: Randy Dunlap 
Acked-by: Randy Dunlap 
Disliked-by: Akira Yokosawa 
Link: https://lore.kernel.org/r/20220218181628.1411551-6-tomasz.warniello@gmail.com
Signed-off-by: Jonathan Corbet

scripts: kernel-doc: Translate the "Output format selection" subsection of OPTIONS

2022-02-24T17:52:46+00:00

Another step in the direction of a uniform POD documentation, which will
make users happier.

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.

A POD delimiting comment is added to the script head, which improves
the script logical structure.

Signed-off-by: Tomasz Warniełło 
Tested-by: Randy Dunlap 
Acked-by: Randy Dunlap 
Disliked-by: Akira Yokosawa 
Link: https://lore.kernel.org/r/20220218181628.1411551-5-tomasz.warniello@gmail.com
Signed-off-by: Jonathan Corbet