e4153a22 | 21-Jun-2025 |
Jonathan Corbet <corbet@lwn.net> |
docs: kdoc: separate out the handling of the declaration phase
The BODY_MAYBE state really describes the "we are in a declaration" state. Rename it accordingly, and split the handling of this state
docs: kdoc: separate out the handling of the declaration phase
The BODY_MAYBE state really describes the "we are in a declaration" state. Rename it accordingly, and split the handling of this state out from that of the other BODY* states. This change introduces a fair amount of duplicated code that will be coalesced in a later patch.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250621203512.223189-4-corbet@lwn.net
show more ...
|
df275526 | 21-Jun-2025 |
Jonathan Corbet <corbet@lwn.net> |
docs: kdoc: consolidate the "begin section" logic
Pull the repeated "begin a section" logic into a single place and hide it within the KernelEntry class.
Reviewed-by: Mauro Carvalho Chehab <mchehab
docs: kdoc: consolidate the "begin section" logic
Pull the repeated "begin a section" logic into a single place and hide it within the KernelEntry class.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250621203512.223189-3-corbet@lwn.net
show more ...
|
823d6f95 | 21-Jun-2025 |
Jonathan Corbet <corbet@lwn.net> |
docs: kdoc: Make body_with_blank_line parsing more flexible
The regex in the BODY_WITH_BLANK_LINE case was looking for lines starting with " * ", where exactly one space was allowed before the follo
docs: kdoc: Make body_with_blank_line parsing more flexible
The regex in the BODY_WITH_BLANK_LINE case was looking for lines starting with " * ", where exactly one space was allowed before the following text. There are many kerneldoc comments where the authors have put multiple spaces instead, leading to mis-formatting of the documentation. Specifically, in this case, the description portion is associated with the last of the parameters.
Allow multiple spaces in this context.
See, for example, synchronize_hardirq() and how its documentation is formatted before and after the change.
Acked-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Tested-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250621203512.223189-2-corbet@lwn.net
show more ...
|
8666a352 | 06-Jun-2025 |
Jonathan Corbet <corbet@lwn.net> |
docs: kdoc: some final touches for process_name()
Add some comments to process_name() to cover its broad phases of operation, and slightly restructure the if/then/else structure to remove some early
docs: kdoc: some final touches for process_name()
Add some comments to process_name() to cover its broad phases of operation, and slightly restructure the if/then/else structure to remove some early returns.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250606163438.229916-10-corbet@lwn.net
show more ...
|
0682bde2 | 06-Jun-2025 |
Jonathan Corbet <corbet@lwn.net> |
docs: kdoc: move the declaration regexes out of process_name()
Move two complex regexes up with the other patterns, decluttering this function and allowing the compilation to be done once rather tha
docs: kdoc: move the declaration regexes out of process_name()
Move two complex regexes up with the other patterns, decluttering this function and allowing the compilation to be done once rather than for every kerneldoc comment.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250606163438.229916-9-corbet@lwn.net
show more ...
|
b23c7108 | 06-Jun-2025 |
Jonathan Corbet <corbet@lwn.net> |
docs: kdoc: remove some ineffective code
The code testing for a pointer declaration in process_name() has no actual effect on subsequent actions; remove it.
Reviewed-by: Mauro Carvalho Chehab <mche
docs: kdoc: remove some ineffective code
The code testing for a pointer declaration in process_name() has no actual effect on subsequent actions; remove it.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250606163438.229916-8-corbet@lwn.net
show more ...
|
f9b4cf2e | 06-Jun-2025 |
Jonathan Corbet <corbet@lwn.net> |
docs: kdoc: remove the KernelEntry::descr pseudo member
The entry.descr value used in process_name() is not actually a member of the KernelEntry class; it is a bit of local state. So just manage it
docs: kdoc: remove the KernelEntry::descr pseudo member
The entry.descr value used in process_name() is not actually a member of the KernelEntry class; it is a bit of local state. So just manage it locally.
A trim_whitespace() helper was added to clean up the code slightly.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250606163438.229916-7-corbet@lwn.net
show more ...
|
8f4650fe | 06-Jun-2025 |
Jonathan Corbet <corbet@lwn.net> |
docs: kdoc: remove the KernelEntry::is_kernel_comment member
entry::is_kernel_comment never had anything to do with the entry itself; it is a bit of local state in one branch of process_name(). It
docs: kdoc: remove the KernelEntry::is_kernel_comment member
entry::is_kernel_comment never had anything to do with the entry itself; it is a bit of local state in one branch of process_name(). It can, in fact, be removed entirely; rework the code slightly so that it is no longer needed.
No change in the rendered output.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250606163438.229916-6-corbet@lwn.net
show more ...
|
e76a1d2b | 06-Jun-2025 |
Jonathan Corbet <corbet@lwn.net> |
docs: kdoc: simplify the kerneldoc recognition code
process_name() looks for the first line of a kerneldoc comment. It contains two nearly identical regular expressions, the second of which only ca
docs: kdoc: simplify the kerneldoc recognition code
process_name() looks for the first line of a kerneldoc comment. It contains two nearly identical regular expressions, the second of which only catches six cases in the kernel, all of the form:
define SOME_MACRO_NAME - description
Simply put the "define" into the regex and discard it, eliminating the loop and the code to remove it specially.
Note that this still treats these defines as if they were functions, but that's a separate issue.
There is no change in the generated output.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250606163438.229916-5-corbet@lwn.net
show more ...
|
42592bd4 | 06-Jun-2025 |
Jonathan Corbet <corbet@lwn.net> |
docs: kdoc: remove the section_intro variable
It is only used in one place, so just put the constant string "Introduction" there so people don't have to go looking for it.
Reviewed-by: Mauro Carval
docs: kdoc: remove the section_intro variable
It is only used in one place, so just put the constant string "Introduction" there so people don't have to go looking for it.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250606163438.229916-4-corbet@lwn.net
show more ...
|
cef8c781 | 06-Jun-2025 |
Jonathan Corbet <corbet@lwn.net> |
docs: kdoc: move the core dispatch into a state table
Since all of the handlers already nicely have the same prototype, put them into a table and call them from there and take out the extended if-th
docs: kdoc: move the core dispatch into a state table
Since all of the handlers already nicely have the same prototype, put them into a table and call them from there and take out the extended if-then-else series.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250606163438.229916-3-corbet@lwn.net
show more ...
|
e3b42e94 | 25-Apr-2025 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
scripts/lib/kdoc/kdoc_parser.py: move kernel entry to a class
The KernelDoc class is too complex. Start optimizing it by placing the kernel-doc parser entry to a separate class.
Signed-off-by: Maur
scripts/lib/kdoc/kdoc_parser.py: move kernel entry to a class
The KernelDoc class is too complex. Start optimizing it by placing the kernel-doc parser entry to a separate class.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <28b456f726a022011f0ce5810dbcc26827c1403a.1745564565.git.mchehab+huawei@kernel.org>
show more ...
|
47c2d416 | 15-Apr-2025 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
scripts:kdoc_files.py: use glob for export_file seek
As filenames are expanded using kernel-doc glob, just in case, use it also when checking for exported symbols.
Signed-off-by: Mauro Carvalho Che
scripts:kdoc_files.py: use glob for export_file seek
As filenames are expanded using kernel-doc glob, just in case, use it also when checking for exported symbols.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/21657afdd4f8effe0752a5ec258d74b8a4101f55.1744685912.git.mchehab+huawei@kernel.org
show more ...
|
f9cdbc57 | 15-Apr-2025 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
scripts/lib/kdoc/kdoc_parser.py: move states to a separate class
States are really enums. on Python, enums are actually classes, as can be seen at: https://docs.python.org/3/library/enum.html
Yet,
scripts/lib/kdoc/kdoc_parser.py: move states to a separate class
States are really enums. on Python, enums are actually classes, as can be seen at: https://docs.python.org/3/library/enum.html
Yet, I can't see any advantage of derivating the class from enum class here. So, just place the states on a separate class.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/00cb4e0b8a1545bf7c4401b58213841db5cba2e2.1744685912.git.mchehab+huawei@kernel.org
show more ...
|
de258fa8 | 08-Apr-2025 |
Sean Anderson <sean.anderson@linux.dev> |
scripts: kernel-doc: fix parsing function-like typedefs (again)
Typedefs like
typedef struct phylink_pcs *(*pcs_xlate_t)(const u64 *args);
have a typedef_type that ends with a * and therefore
scripts: kernel-doc: fix parsing function-like typedefs (again)
Typedefs like
typedef struct phylink_pcs *(*pcs_xlate_t)(const u64 *args);
have a typedef_type that ends with a * and therefore has no word boundary. Add an extra clause for the final group of the typedef_type so we only require a word boundary if we match a word.
[mchehab: modify also kernel-doc.py, as we're deprecating the perl version]
Fixes: 7d2c6b1edf79 ("scripts: kernel-doc: fix parsing function-like typedefs") Signed-off-by: Sean Anderson <sean.anderson@linux.dev> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/e0abb103c73a96d76602d909f60ab8fd6e2fd0bd.1744106242.git.mchehab+huawei@kernel.org
show more ...
|
04a383ce | 08-Apr-2025 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
scripts/kernel-doc.py: Rename the kernel doc Re class to KernRe
Using just "Re" makes it harder to distinguish from the native "re" class. So, let's rename it.
Signed-off-by: Mauro Carvalho Chehab
scripts/kernel-doc.py: Rename the kernel doc Re class to KernRe
Using just "Re" makes it harder to distinguish from the native "re" class. So, let's rename it.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/4e095ecd5235a3e811ddcf5bad4cfb92f1da0a4a.1744106242.git.mchehab+huawei@kernel.org
show more ...
|
16740c29 | 08-Apr-2025 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
scripts/kernel_doc.py: better handle exported symbols
Change the logic which detects internal/external symbols in a way that we can re-use it when calling via Sphinx extension.
While here, remove a
scripts/kernel_doc.py: better handle exported symbols
Change the logic which detects internal/external symbols in a way that we can re-use it when calling via Sphinx extension.
While here, remove an unused self.config var and let it clearer that self.config variables are read-only. This helps to allow handling multiple times in parallel if ever needed.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/6a69ba8d2b7ee6a6427abb53e60d09bd4d3565ee.1744106242.git.mchehab+huawei@kernel.org
show more ...
|
a566ba5a | 08-Apr-2025 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
scripts/lib/kdoc/kdoc_files.py: allow filtering output per fname
For kerneldoc Sphinx extension, it is useful to display parsed results only from a single file. Change the logic at KernelFiles.msg()
scripts/lib/kdoc/kdoc_files.py: allow filtering output per fname
For kerneldoc Sphinx extension, it is useful to display parsed results only from a single file. Change the logic at KernelFiles.msg() to allow such usage.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/9f5c0ff2568f34532ca99465fb378241d831d39f.1744106242.git.mchehab+huawei@kernel.org
show more ...
|
11afeab6 | 08-Apr-2025 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
scripts/kernel-doc.py: Properly handle Werror and exit codes
The original kernel-doc script has a logic to return warnings as errors, and to report the number of warnings found, if in verbose mode.
scripts/kernel-doc.py: Properly handle Werror and exit codes
The original kernel-doc script has a logic to return warnings as errors, and to report the number of warnings found, if in verbose mode.
Implement it to be fully compatible with the original script.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/de33b0cebd9fdf82d8b221bcfe41db7269286222.1744106242.git.mchehab+huawei@kernel.org
show more ...
|
e4b2bd90 | 08-Apr-2025 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
scripts/lib/kdoc/kdoc_parser.py: remove a python 3.9 dependency
str.removesuffix() was added on Python 3.9, but rstrip() actually does the same thing, as we just want to remove a single character. I
scripts/lib/kdoc/kdoc_parser.py: remove a python 3.9 dependency
str.removesuffix() was added on Python 3.9, but rstrip() actually does the same thing, as we just want to remove a single character. It is also shorter.
So, use it.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/f64cc4adef107ada26da4bfb7e4b7002dd783173.1744106242.git.mchehab+huawei@kernel.org
show more ...
|