kernel-doc: handle a void function without producing a warning

Currently a void function can produce a warning:
main.c:469: warning: contents before sections

This one is from arch/x86/kernel/cpu/

kernel-doc: handle a void function without producing a warning

Currently a void function can produce a warning:
main.c:469: warning: contents before sections

This one is from arch/x86/kernel/cpu/sgx/main.c (which is not included
in any produced kernel documentation output).

Handle this by setting $in_doc_sect to 1 whenever any recognized
document section name is processed.

Fixes: f624adef3d0b ("kernel-doc: limit the "section header:" detection to a select few")
Signed-off-by: Randy Dunlap <[email protected]>
Cc: Jani Nikula <[email protected]>
Cc: Jonathan Corbet <[email protected]>
Cc: [email protected]
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

kernel-doc: Align quick help and the code

The update to the quick help mentions -Wshort-description, but
code never supported for that. Align that with the code by allowing
both: -Wshort-description

kernel-doc: Align quick help and the code

The update to the quick help mentions -Wshort-description, but
code never supported for that. Align that with the code by allowing
both: -Wshort-description and -Wshort-desc.

Fixes: 56b0f453db74 ("kernel-doc: don't let V=1 change outcome")
Signed-off-by: Andy Shevchenko <[email protected]>
Reviewed-by: Randy Dunlap <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

docs: ignore __counted_by attribute in structure definitions

kernel-doc appeared to ignore __counted_by, but appearances can be
deceiving; it caused member names to not be recognized, which manifest

docs: ignore __counted_by attribute in structure definitions

kernel-doc appeared to ignore __counted_by, but appearances can be
deceiving; it caused member names to not be recognized, which manifested as
a number of spurious "Excess struct member" warnings. Filter that
attribute out and reduce the warning onslaught slightly.

Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

scripts: kernel-doc: Clarify missing struct member description

The output "or member" should be more specific, instead saying "struct
member".

Cc: Jonathan Corbet <[email protected]>
Cc: linux-doc@vge

scripts: kernel-doc: Clarify missing struct member description

The output "or member" should be more specific, instead saying "struct
member".

Cc: Jonathan Corbet <[email protected]>
Cc: [email protected]
Signed-off-by: Kees Cook <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

scripts/kernel-doc: restore warning for Excess struct/union

The warning for Excess struct or union member description was
removed when the $nested parameter of check_sections() was removed.
This cau

scripts/kernel-doc: restore warning for Excess struct/union

The warning for Excess struct or union member description was
removed when the $nested parameter of check_sections() was removed.
This causes some kernel-doc notation warnings to be missed.

Recently the kernel test robot somehow reported an Excess member. The
code in kernel-doc has not issued that warning since kernel v4.16, so I
don't know how the robot did it. (See the Link for the report.)

drivers/net/wireless/intel/iwlwifi/fw/dbg.c:86: warning: Excess struct/union/enum/typedef member 'trans_len' description in 'iwl_fw_dump_ptrs'

I patched that warning away even though I could not reproduce the
warning from kernel-doc. The warning should be issued for extraneous
struct member or union member description, so restore it.

Fixes: 1081de2d2f91 ("scripts: kernel-doc: get rid of $nested parameter")
Signed-off-by: Randy Dunlap <[email protected]>
Link: https://lore.kernel.org/all/[email protected]/
Cc: Mauro Carvalho Chehab <[email protected]>
Cc: Jonathan Corbet <[email protected]>
Cc: [email protected]
Reviewed-by: Kees Cook <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

cache: enforce cache groups

Set up build time warnings to safeguard against future header changes of
organized structs.

Warning includes:

1) whether all variables are still in the same cache group

cache: enforce cache groups

Set up build time warnings to safeguard against future header changes of
organized structs.

Warning includes:

1) whether all variables are still in the same cache group
2) whether all the cache groups have the sum of the members size (in the
maximum condition, including all members defined in configs)

The __cache_group* variables are ignored in kernel-doc check in the
various header files they appear in to enforce the cache groups.

Suggested-by: Daniel Borkmann <[email protected]>
Acked-by: Daniel Borkmann <[email protected]>
Signed-off-by: Coco Li <[email protected]>
Reviewed-by: Eric Dumazet <[email protected]>
Reviewed-by: Shakeel Butt <[email protected]>
Signed-off-by: David S. Miller <[email protected]>

show more ...

scripts/kernel-doc: Fix the regex for matching -Werror flag

Swarup reported a "make htmldocs" warning:

Variable length lookbehind is experimental in regex;
marked by <-- HERE in m/(?<=^|\s)-Wer

scripts/kernel-doc: Fix the regex for matching -Werror flag

Swarup reported a "make htmldocs" warning:

Variable length lookbehind is experimental in regex;
marked by <-- HERE in m/(?<=^|\s)-Werror(?=$|\s)
<-- HERE / at ./scripts/kernel-doc line 188.

Akira managed to reproduce it by perl v5.34.0.

On second thought, it is not necessary to have the complicated
"lookahead and lookbehind" things, and the regex can be simplified.

Generally, the kernel-doc warnings should be considered as errors only
when "-Werror" flag is set in KCFLAGS, but not when
"-Werror=<diagnostic-type>" is set, which means there needs to be a
space or start of string before "-Werror", and a space or end of string
after "-Werror".

The following cases have been tested to work as expected:

* kernel-doc warnings are considered as errors:

$ KCFLAGS="-Werror" make W=1
$ KCFLAGS="-Wcomment -Werror" make W=1
$ KCFLAGS="-Werror -Wundef" make W=1
$ KCFLAGS="-Wcomment -Werror -Wundef" make W=1

* kernel-doc warnings remain as warnings:

$ KCFLAGS="-Werror=return-type" make W=1
$ KCFLAGS="-Wcomment -Werror=return-type" make W=1
$ KCFLAGS="-Werror=return-type -Wundef" make W=1
$ KCFLAGS="-Wcomment -Werror=return-type -Wundef" make W=1

The "Variable length lookbehind is experimental in regex" warning is
also resolved by this patch.

Fixes: 91f950e8b9d8 ("scripts/kernel-doc: match -Werror flag strictly")
Reported-by: Swarup Laxman Kotiaklapudi <[email protected]>
Signed-off-by: Yujie Liu <[email protected]>
Closes: https://lore.kernel.org/r/[email protected]/
Reviewed-by: Akira Yokosawa <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

scripts/kernel-doc: match -Werror flag strictly

In our CI testing, we use some commands as below to only turn a specific
type of warnings into errors, but we notice that kernel-doc warnings
are also

scripts/kernel-doc: match -Werror flag strictly

In our CI testing, we use some commands as below to only turn a specific
type of warnings into errors, but we notice that kernel-doc warnings
are also turned into errors unexpectedly.

$ make KCFLAGS="-Werror=return-type" W=1 kernel/fork.o

kernel/fork.c:1406: warning: Function parameter or member 'mm' not described in 'set_mm_exe_file'
kernel/fork.c:1406: warning: Function parameter or member 'new_exe_file' not described in 'set_mm_exe_file'
kernel/fork.c:1441: warning: Function parameter or member 'mm' not described in 'replace_mm_exe_file'
kernel/fork.c:1441: warning: Function parameter or member 'new_exe_file' not described in 'replace_mm_exe_file'
kernel/fork.c:1491: warning: Function parameter or member 'mm' not described in 'get_mm_exe_file'
kernel/fork.c:1510: warning: Function parameter or member 'task' not described in 'get_task_exe_file'
kernel/fork.c:1534: warning: Function parameter or member 'task' not described in 'get_task_mm'
kernel/fork.c:2109: warning: bad line:
kernel/fork.c:2130: warning: Function parameter or member 'ret' not described in '__pidfd_prepare'
kernel/fork.c:2130: warning: Excess function parameter 'pidfd' description in '__pidfd_prepare'
kernel/fork.c:2179: warning: Function parameter or member 'ret' not described in 'pidfd_prepare'
kernel/fork.c:2179: warning: Excess function parameter 'pidfd' description in 'pidfd_prepare'
kernel/fork.c:3195: warning: expecting prototype for clone3(). Prototype was for sys_clone3() instead
13 warnings as Errors
make[3]: *** [scripts/Makefile.build:243: kernel/fork.o] Error 13
make[3]: *** Deleting file 'kernel/fork.o'
make[2]: *** [scripts/Makefile.build:480: kernel] Error 2
make[1]: *** [/root/linux/Makefile:1913: .] Error 2
make: *** [Makefile:234: __sub-make] Error 2

>From the git history, commit 2c12c8103d8f ("scripts/kernel-doc:
optionally treat warnings as errors") introduces a new command-line
option to make kernel-doc warnings into errors. It can also read the
KCFLAGS environment variable to decide whether to turn this option on,
but the regex used for matching may not be accurate enough. It can match
both "-Werror" and "-Werror=<diagnostic-type>", so the option is turned
on by mistake in the latter case.

Fix this by strictly matching the flag "-Werror": there must be a space
or start of string in the front, and a space or end of string at the
end. This can handle all the following cases correctly:

KCFLAGS="-Werror" make W=1 [MATCH]
KCFLAGS="-Werror=return-type" make W=1 [NO MATCH]
KCFLAGS="-Wcomment -Werror -Wundef" make W=1 [MATCH]
KCFLAGS="-Wcomment -Werror=return-type -Wundef" make W=1 [NO MATCH]

Fixes: 2c12c8103d8f ("scripts/kernel-doc: optionally treat warnings as errors")
Signed-off-by: Yujie Liu <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Message-ID: <[email protected]>

show more ...

scripts: kernel-doc: fix macro handling in enums

drivers/net/ethernet/intel/idpf/idpf.h uses offsetof to
initialize the enum enumerators:

enum idpf_cap_field {
IDPF_BASE_CAPS = -1,
IDPF_CSUM_CAPS

scripts: kernel-doc: fix macro handling in enums

drivers/net/ethernet/intel/idpf/idpf.h uses offsetof to
initialize the enum enumerators:

enum idpf_cap_field {
IDPF_BASE_CAPS = -1,
IDPF_CSUM_CAPS = offsetof(struct virtchnl2_get_capabilities,
csum_caps),
IDPF_SEG_CAPS = offsetof(struct virtchnl2_get_capabilities,
seg_caps),
IDPF_RSS_CAPS = offsetof(struct virtchnl2_get_capabilities,
rss_caps),
IDPF_HSPLIT_CAPS = offsetof(struct virtchnl2_get_capabilities,
hsplit_caps),
IDPF_RSC_CAPS = offsetof(struct virtchnl2_get_capabilities,
rsc_caps),
IDPF_OTHER_CAPS = offsetof(struct virtchnl2_get_capabilities,
other_caps),
};

kernel-doc parses the above enumerator with a ',' inside the
macro and treats 'csum_caps', 'seg_caps' etc. also as enumerators
resulting in the warnings:

drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value
'csum_caps' not described in enum 'idpf_cap_field'
drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value
'seg_caps' not described in enum 'idpf_cap_field'
drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value
'rss_caps' not described in enum 'idpf_cap_field'
drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value
'hsplit_caps' not described in enum 'idpf_cap_field'
drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value
'rsc_caps' not described in enum 'idpf_cap_field'
drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value
'other_caps' not described in enum 'idpf_cap_field'

Fix it by removing the macro arguments within the parentheses.

Cc: Jonathan Corbet <[email protected]>
Signed-off-by: Pavan Kumar Linga <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

scripts: kernel-doc: parse DEFINE_DMA_UNMAP_[ADDR|LEN]

At present, if the macros DEFINE_DMA_UNMAP_ADDR() and
DEFINE_DMA_UNMAP_LEN() are used in the structures as shown
below, instead of parsing the

scripts: kernel-doc: parse DEFINE_DMA_UNMAP_[ADDR|LEN]

At present, if the macros DEFINE_DMA_UNMAP_ADDR() and
DEFINE_DMA_UNMAP_LEN() are used in the structures as shown
below, instead of parsing the parameter in the parentheses,
kernel-doc parses 'DEFINE_DMA_UNMAP_ADDR(' and
'DEFINE_DMA_UNMAP_LEN(' which results in the following
warnings:

drivers/net/ethernet/intel/idpf/idpf_txrx.h:201: warning: Function
parameter or member 'DEFINE_DMA_UNMAP_ADDR(dma' not described in
'idpf_tx_buf'
drivers/net/ethernet/intel/idpf/idpf_txrx.h:201: warning: Function
parameter or member 'DEFINE_DMA_UNMAP_LEN(len' not described in
'idpf_tx_buf'

struct idpf_tx_buf {
DEFINE_DMA_UNMAP_ADDR(dma);
DEFINE_DMA_UNMAP_LEN(len);
};

Fix the warnings by parsing DEFINE_DMA_UNMAP_ADDR() and
DEFINE_DMA_UNMAP_LEN().

Cc: Jonathan Corbet <[email protected]>
Acked-by: Randy Dunlap <[email protected]>
Signed-off-by: Pavan Kumar Linga <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

scripts: kernel-doc: support private / public marking for enums

Enums benefit from private markings, too. For netlink attribute
name enums always end with a pair of __$n_MAX and $n_MAX members.
Docu

scripts: kernel-doc: support private / public marking for enums

Enums benefit from private markings, too. For netlink attribute
name enums always end with a pair of __$n_MAX and $n_MAX members.
Documenting them feels a bit tedious.

Signed-off-by: Jakub Kicinski <[email protected]>
Reviewed-by: Randy Dunlap <[email protected]>
Tested-by: Randy Dunlap <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Message-ID: <[email protected]>

show more ...

kernel-doc: don't let V=1 change outcome

The kernel-doc script currently reports a number of issues
only in "verbose" mode, but that's initialized from V=1
(via KBUILD_VERBOSE), so if you use KDOC_W

kernel-doc: don't let V=1 change outcome

The kernel-doc script currently reports a number of issues
only in "verbose" mode, but that's initialized from V=1
(via KBUILD_VERBOSE), so if you use KDOC_WERROR=1 then
adding V=1 might actually break the build. This is rather
unexpected.

Change kernel-doc to not change its behaviour wrt. errors
(or warnings) when verbose mode is enabled, but rather add
separate warning flags (and -Wall) for it. Allow enabling
those flags via environment/make variables in the kernel's
build system for easier user use, but to not have to parse
them in the script itself.

Signed-off-by: Johannes Berg <[email protected]>
Acked-by: Jonathan Corbet <[email protected]>
Signed-off-by: Masahiro Yamada <[email protected]>

show more ...

docs: scripts: kernel-doc: accept bitwise negation like ~@var

In some cases we'd like to indicate the bitwise negation of a parameter,
e.g.

~@var

This will be helpful for describing the atomic a

docs: scripts: kernel-doc: accept bitwise negation like ~@var

In some cases we'd like to indicate the bitwise negation of a parameter,
e.g.

~@var

This will be helpful for describing the atomic andnot operations, where
we'd like to write comments of the form:

Atomically updates @v to (@v & ~@i)

Which kernel-doc currently transforms to:

Atomically updates **v** to (**v** & ~**i**)

Rather than the preferable form:

Atomically updates **v** to (**v** & **~i**)

This is similar to what we did for '!@var' in commit:

ee2aa7590398 ("scripts: kernel-doc: accept negation like !@var")

This patch follows the same pattern that commit used to permit a '!'
prefix on a param ref, allowing a '~' prefix on a param ref, cuasing
kernel-doc to generate the preferred form above.

Suggested-by: Akira Yokosawa <[email protected]>
Signed-off-by: Mark Rutland <[email protected]>
Signed-off-by: Peter Zijlstra (Intel) <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

scripts: kernel-doc: Remove workaround for @param... syntax

Commit 43756e347f21 ("scripts/kernel-doc: Add support for named variable
macro arguments") improved how named variable macro arguments are

scripts: kernel-doc: Remove workaround for @param... syntax

Commit 43756e347f21 ("scripts/kernel-doc: Add support for named variable
macro arguments") improved how named variable macro arguments are
handled, and changed how they are documented in kerneldoc comments
from "@param...", to "@param", deprecating the old syntax.

All users of the old syntax have since been converted, so this commit
finally removes support for it.

The output of "make htmldocs" is the same with and without this commit.

Signed-off-by: Jonathan Neuschäfer <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

kbuild: do not print extra logs for V=2

Some scripts increase the verbose level when V=1, but others when
not V=0.

I think the former is correct because V=2 is not a log level but
a switch to print

kbuild: do not print extra logs for V=2

Some scripts increase the verbose level when V=1, but others when
not V=0.

I think the former is correct because V=2 is not a log level but
a switch to print the reason for rebuilding.

Signed-off-by: Masahiro Yamada <[email protected]>
Reviewed-by: Nicolas Schier <[email protected]>

show more ...

scripts/kernel-doc: support EXPORT_SYMBOL_NS_GPL() with -export

Parse EXPORT_SYMBOL_NS_GPL() in addition to EXPORT_SYMBOL_GPL() for use
with the -export flag.

Link: https://lore.kernel.org/r/4-v6-a

scripts/kernel-doc: support EXPORT_SYMBOL_NS_GPL() with -export

Parse EXPORT_SYMBOL_NS_GPL() in addition to EXPORT_SYMBOL_GPL() for use
with the -export flag.

Link: https://lore.kernel.org/r/[email protected]
Acked-by: Jonathan Corbet <[email protected]>
Signed-off-by: Jason Gunthorpe <[email protected]>

show more ...

string: Rewrite and add more kern-doc for the str*() functions

While there were varying degrees of kern-doc for various str*()-family
functions, many needed updating and clarification, or to just be

string: Rewrite and add more kern-doc for the str*() functions

While there were varying degrees of kern-doc for various str*()-family
functions, many needed updating and clarification, or to just be
entirely written. Update (and relocate) existing kern-doc and add missing
functions, sadly shaking my head at how many times I have written "Do
not use this function". Include the results in the core kernel API doc.

Cc: Bagas Sanjaya <[email protected]>
Cc: Andy Shevchenko <[email protected]>
Cc: Rasmus Villemoes <[email protected]>
Cc: Andrew Morton <[email protected]>
Cc: [email protected]
Tested-by: Akira Yokosawa <[email protected]>
Link: https://lore.kernel.org/lkml/[email protected]
Signed-off-by: Kees Cook <[email protected]>

show more ...

docs: improve the HTML formatting of kerneldoc comments

Make a few changes to cause functions documented by kerneldoc to stand out
better in the rendered documentation. Specifically, change kernel-

docs: improve the HTML formatting of kerneldoc comments

Make a few changes to cause functions documented by kerneldoc to stand out
better in the rendered documentation. Specifically, change kernel-doc to
put the description section into a ".. container::" section, then add a bit
of CSS to indent that section relative to the function prototype (or struct
or enum definition). Tweak a few other CSS parameters while in the
neighborhood to improve the formatting.

Acked-by: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

scripts: kernel-doc: Always increment warnings counter

Some warnings do not increment the warnings counter making the behavior
of running kernel-doc with -Werror unlogical as some warnings will be
g

scripts: kernel-doc: Always increment warnings counter

Some warnings do not increment the warnings counter making the behavior
of running kernel-doc with -Werror unlogical as some warnings will be
generated but not treated as errors.

Fix this by creating a helper function that always incrementing the
warnings counter every time a warning is emitted. There is one location
in get_sphinx_version() where a warning is not touched as it concerns
the execution environment of the kernel-doc and not the documentation
being processed.

Incrementing the counter only have effect when running kernel-doc in
either verbose mode (-v or environment variable KBUILD_VERBOSE) or when
treating warnings as errors (-Werror or environment variable
KDOC_WERROR). In both cases the number of warnings printed is printed to
stderr and for the later the exit code of kernel-doc is non-zero if
warnings where encountered.

Simple test case to demo one of the warnings,

$ cat test.c
/**
* foo() - Description
*/
int bar();

# Without this change
$ ./scripts/kernel-doc -Werror -none test.c
test.c:4: warning: expecting prototype for foo(). Prototype was for
bar() instead

# With this change
$ ./scripts/kernel-doc -Werror -none test.c
test.c:4: warning: expecting prototype for foo(). Prototype was for
bar() instead
1 warnings as Errors

Signed-off-by: Niklas Söderlund <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

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

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

#define LINENO

to
..

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

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 <[email protected]>
Link: https://lore.kernel.org/r/40725032b5a4a33db740bf1de397523af958ff8a.1648290305.git.mchehab@kernel.org
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

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

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 fo

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

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 <[email protected]>
Cc: Randy Dunlap <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
[jc: reworked to fix conflict with pod patches]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

scripts: kernel-doc: Refresh the copyright lines

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.

scripts: kernel-doc: Refresh the copyright lines

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 <[email protected]>
Tested-by: Randy Dunlap <[email protected]>
Acked-by: Randy Dunlap <[email protected]>
Disliked-by: Akira Yokosawa <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

scripts: kernel-doc: Drop obsolete comments

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

scripts: kernel-doc: Drop obsolete comments

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 <[email protected]>
Suggested-by: Jani Nikula <[email protected]>
Signed-off-by: Tomasz Warniełło <[email protected]>
Tested-by: Randy Dunlap <[email protected]>
Acked-by: Randy Dunlap <[email protected]>
Disliked-by: Akira Yokosawa <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

scripts: kernel-doc: Replace the usage function

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

You can see the results with:

$ scripts/kernel-doc -help

Signed-off-by: Tomasz Warn

scripts: kernel-doc: Replace the usage function

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 <[email protected]>
Tested-by: Randy Dunlap <[email protected]>
Acked-by: Randy Dunlap <[email protected]>
Disliked-by: Akira Yokosawa <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

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

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

Notes:
- The -help token is added.
- The entries are sort

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

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 <[email protected]>
Tested-by: Randy Dunlap <[email protected]>
Acked-by: Randy Dunlap <[email protected]>
Disliked-by: Akira Yokosawa <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...