aboutsummaryrefslogtreecommitdiffstats
path: root/scripts/lib/kdoc
Commit message (Collapse)AuthorAgeFilesLines
...
| * docs: kdoc: consolidate the "begin section" logicJonathan Corbet2025-06-251-15/+17
| | | | | | | | | | | | | | | | | | Pull the repeated "begin a section" logic into a single place and hide it within the KernelEntry class. Reviewed-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/[email protected]
| * docs: kdoc: Make body_with_blank_line parsing more flexibleJonathan Corbet2025-06-251-1/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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 <[email protected]> Tested-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/[email protected]
| * docs: kdoc: some final touches for process_name()Jonathan Corbet2025-06-091-13/+20
| | | | | | | | | | | | | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/[email protected]
| * docs: kdoc: move the declaration regexes out of process_name()Jonathan Corbet2025-06-091-13/+17
| | | | | | | | | | | | | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/[email protected]
| * docs: kdoc: remove some ineffective codeJonathan Corbet2025-06-091-5/+0
| | | | | | | | | | | | | | | | | | The code testing for a pointer declaration in process_name() has no actual effect on subsequent actions; remove it. Reviewed-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/[email protected]
| * docs: kdoc: remove the KernelEntry::descr pseudo memberJonathan Corbet2025-06-091-6/+8
| | | | | | | | | | | | | | | | | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/[email protected]
| * docs: kdoc: remove the KernelEntry::is_kernel_comment memberJonathan Corbet2025-06-091-8/+8
| | | | | | | | | | | | | | | | | | | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/[email protected]
| * docs: kdoc: simplify the kerneldoc recognition codeJonathan Corbet2025-06-091-16/+8
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/[email protected]
| * docs: kdoc: remove the section_intro variableJonathan Corbet2025-06-091-2/+1
| | | | | | | | | | | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/[email protected]
| * docs: kdoc: move the core dispatch into a state tableJonathan Corbet2025-06-091-13/+17
| | | | | | | | | | | | | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/[email protected]
| * docs: kdoc: simplify the PROTO continuation logicJonathan Corbet2025-06-091-6/+1
| | | | | | | | | | | | | | | | Remove the unneeded "cont" variable and tighten up the code slightly. Reviewed-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/[email protected]
| * kernel-doc: Fix symbol matching for dropped suffixesMatthew Wilcox (Oracle)2025-06-091-0/+8
| | | | | | | | | | | | | | | | | | | | | | | | | | The support for dropping "_noprof" missed dropping the suffix from exported symbols. That meant that using the :export: feature would look for kernel-doc for (eg) krealloc_noprof() and not find the kernel-doc for krealloc(). Fixes: 51a7bf0238c2 (scripts/kernel-doc: drop "_noprof" on function prototypes) Signed-off-by: Matthew Wilcox (Oracle) <[email protected]> Reviewed-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/[email protected]
* | scripts/kernel_doc.py: properly handle VIRTIO_DECLARE_FEATURESPaolo Abeni2025-07-081-0/+1
|/ | | | | | | The mentioned macro introduce by the next patch will foul kdoc; fully expand the mentioned macro to avoid the issue. Signed-off-by: Paolo Abeni <[email protected]>
* scripts: kernel-doc: prevent a KeyError when checking outputMauro Carvalho Chehab2025-05-211-0/+4
| | | | | | | | | | | | If a file sent to KernelFiles.msg() method doesn't exist, instead of producing a KeyError, output an error message. Reported-by: Randy Dunlap <[email protected]> Closes: https://lore.kernel.org/linux-doc/[email protected]/T/#ma43ae9d8d0995b535cf5099e5381dace0410de04 Signed-off-by: Mauro Carvalho Chehab <[email protected]> Acked-by: Akira Yokosawa <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Message-ID: <4efa177f2157a7ec009cc197dfc2d87e6f32b165.1747817887.git.mchehab+huawei@kernel.org>
* scripts/lib/kdoc/kdoc_parser.py: move kernel entry to a classMauro Carvalho Chehab2025-04-281-124/+149
| | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Message-ID: <28b456f726a022011f0ce5810dbcc26827c1403a.1745564565.git.mchehab+huawei@kernel.org>
* scripts/lib/kdoc: change mode to 0644Mauro Carvalho Chehab2025-04-283-0/+0
| | | | | | | | | The script library here contain just classes. Remove execution permission. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Message-ID: <be0b0a5bde82fa09027a5083f8202f150581eb4e.1745564565.git.mchehab+huawei@kernel.org>
* scripts:kdoc_files.py: use glob for export_file seekMauro Carvalho Chehab2025-04-211-1/+3
| | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/21657afdd4f8effe0752a5ec258d74b8a4101f55.1744685912.git.mchehab+huawei@kernel.org
* scripts/lib/kdoc/kdoc_parser.py: move states to a separate classMauro Carvalho Chehab2025-04-211-57/+62
| | | | | | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/00cb4e0b8a1545bf7c4401b58213841db5cba2e2.1744685912.git.mchehab+huawei@kernel.org
* scripts/lib/kdoc/kdoc_files.py: don't try to join NoneMauro Carvalho Chehab2025-04-211-2/+5
| | | | | | | | | If out_msg() returns None, it means that an unknown declaration was found. Avoid letting the script crash on such case. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/4334d16f14cfd93e611b290fb56c35d236cadcb7.1744685912.git.mchehab+huawei@kernel.org
* scripts: kernel-doc: fix parsing function-like typedefs (again)Sean Anderson2025-04-091-1/+1
| | | | | | | | | | | | | | | | | | 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 <[email protected]> Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/e0abb103c73a96d76602d909f60ab8fd6e2fd0bd.1744106242.git.mchehab+huawei@kernel.org
* scripts/kernel-doc.py: Rename the kernel doc Re class to KernReMauro Carvalho Chehab2025-04-093-159/+159
| | | | | | | | | Using just "Re" makes it harder to distinguish from the native "re" class. So, let's rename it. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/4e095ecd5235a3e811ddcf5bad4cfb92f1da0a4a.1744106242.git.mchehab+huawei@kernel.org
* scripts/kernel_doc.py: better handle exported symbolsMauro Carvalho Chehab2025-04-093-78/+123
| | | | | | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/6a69ba8d2b7ee6a6427abb53e60d09bd4d3565ee.1744106242.git.mchehab+huawei@kernel.org
* scripts/lib/kdoc/kdoc_files.py: allow filtering output per fnameMauro Carvalho Chehab2025-04-091-12/+12
| | | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/9f5c0ff2568f34532ca99465fb378241d831d39f.1744106242.git.mchehab+huawei@kernel.org
* scripts/kernel-doc.py: Properly handle Werror and exit codesMauro Carvalho Chehab2025-04-093-16/+19
| | | | | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/de33b0cebd9fdf82d8b221bcfe41db7269286222.1744106242.git.mchehab+huawei@kernel.org
* scripts/lib/kdoc/kdoc_parser.py: remove a python 3.9 dependencyMauro Carvalho Chehab2025-04-091-1/+1
| | | | | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/f64cc4adef107ada26da4bfb7e4b7002dd783173.1744106242.git.mchehab+huawei@kernel.org
* scripts/kernel-doc.py: properly handle KBUILD_BUILD_TIMESTAMPMauro Carvalho Chehab2025-04-092-16/+21
| | | | | | | | | | | The logic that handles KBUILD_BUILD_TIMESTAMP is wrong, and adds a dependency of a third party module (dateutil). Fix it. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/ffc70a1b741b010365ed82f31611018f24f91ce7.1744106242.git.mchehab+huawei@kernel.org
* scripts/kernel-doc.py: move modulename to man classMauro Carvalho Chehab2025-04-093-19/+8
| | | | | | | | | Only man output requires a modulename. Move its definition to the man class. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/583085e3885b0075d16ef9961b4f2ad870f30a55.1744106242.git.mchehab+huawei@kernel.org
* scripts/lib/kdoc/kdoc_parser.py: fix Python compat with < v3.13Mauro Carvalho Chehab2025-04-092-6/+6
| | | | | | | | | | - str.replace count was introduced only in Python 3.13; - before Python 3.13, f-string dict arguments can't use the same delimiter of the main string. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/e2b8e8361294558dae09236e4b8fbea5d86be5a3.1744106242.git.mchehab+huawei@kernel.org
* scripts/kernel-doc.py: adjust some coding style issuesMauro Carvalho Chehab2025-04-094-37/+50
| | | | | | | | | Make pylint happier by adding some missing documentation and addressing a couple of pylint warnings. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/0f9d5473105e4c09c6c41e3db72cc63f1d4d55f9.1744106242.git.mchehab+huawei@kernel.org
* scripts/kernel-doc.py: Set an output format for --noneMauro Carvalho Chehab2025-04-091-0/+4
| | | | | | | | | | | Now that warnings output is deferred to the output plugin, we need to have an output style for none as well. So, use the OutputFormat base class on such cases. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/caa1089e16f4609f792ff26731ad9e9c3a6f6b1d.1744106242.git.mchehab+huawei@kernel.org
* scripts/kernel-doc.py: postpone warnings to the output pluginMauro Carvalho Chehab2025-04-092-26/+39
| | | | | | | | | | We don't want to have warnings displayed for symbols that weren't output. So, postpone warnings print to the output plugin, where symbol output is validated. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/e6344711e390cf22af02a56bb5dd51ca67c0afb6.1744106242.git.mchehab+huawei@kernel.org
* scripts/kernel-doc.py: properly handle out_section for ReSTMauro Carvalho Chehab2025-04-091-4/+4
| | | | | | | | | There is a difference at the way DOC sections are output with the include mode. Handle such difference properly. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/935d00c6a7c45b25a8be72fad6183fe5a8476cd2.1744106242.git.mchehab+huawei@kernel.org
* scripts/kernel-doc.py: fix handling of doc output checkMauro Carvalho Chehab2025-04-092-18/+14
| | | | | | | | | | | | | | | The filtering logic was seeking for the DOC name to check for symbols, but such data is stored only inside a section. Add it to the output_declaration, as it is quicker/easier to check the declaration name than to check inside each section. While here, make sure that the output for both ReST and man after filtering will be similar to what kernel-doc Perl version does. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/6d8b77af85295452c0191863ea1041f4195aeaaf.1744106242.git.mchehab+huawei@kernel.org
* scripts/kernel-doc.py: fix line number outputMauro Carvalho Chehab2025-04-092-10/+24
| | | | | | | | | | | | With the Pyhton version, the actual output happens after parsing, from records stored at self.entries. Ensure that line numbers will be properly stored there and that they'll produce the desired results at the ReST output. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/5182a531d14b5fe9e1fc5da5f9dae05d66852a60.1744106242.git.mchehab+huawei@kernel.org
* scripts/kernel-doc.py: implement support for -no-doc-sectionsMauro Carvalho Chehab2025-04-092-3/+9
| | | | | | | | | | | | The venerable kernel-doc Perl script has a number of options that aren't properly documented. Among them, there is -no-doc-sections, which is used by the Sphinx extension. Implement support for it. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/06b18a32142b44d5ba8b41ac64a76c02b03b4969.1744106242.git.mchehab+huawei@kernel.org
* scripts/kernel-doc.py: move file lists to the parser functionMauro Carvalho Chehab2025-04-091-20/+17
| | | | | | | | | | | | | | | | | Instead of setting file lists at __init__ time, move it to the actual parsing function. This allows adding more files to be parsed in real time, by calling parse function multiple times. With the new way, the export_files logic was rewritten to avoid parsing twice EXPORT_SYMBOL for partial matches. Please notice that, with this logic, it can still read the same file twice when export_file is used. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/ab10bc94050406ce6536d4944b5d718ecd70812f.1744106242.git.mchehab+huawei@kernel.org
* scripts/kernel-doc.py: convert message output to an interactorMauro Carvalho Chehab2025-04-092-88/+98
| | | | | | | | | | Instead of directly printing output messages, change kdoc classes to return an interactor with the output message, letting the actual display to happen at the command-line command. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/557304c8458f1fb4aa2e833f4bdaff953094ddcb.1744106242.git.mchehab+huawei@kernel.org
* scripts/kernel-doc.py: move output classes to a separate fileMauro Carvalho Chehab2025-04-091-0/+736
| | | | | | | | | In preparation for letting kerneldoc Sphinx extension to import Python libraries, move kernel-doc output logic to a separate file. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/81087eff25d11c265019a8631f7fc8d3904795d0.1744106242.git.mchehab+huawei@kernel.org
* scripts/kernel-doc.py: move KernelFiles class to a separate fileMauro Carvalho Chehab2025-04-091-0/+270
| | | | | | | | | | | | | The KernelFiles class is the main dispatcher which parses each source file. In preparation for letting kerneldoc Sphinx extension to import Python libraries, move regex ancillary classes to a separate file. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/80bc855e128a9ff0a11df5afe9ba71775dfc9a0f.1744106241.git.mchehab+huawei@kernel.org
* scripts/kernel-doc.py: move KernelDoc class to a separate fileMauro Carvalho Chehab2025-04-091-0/+1690
| | | | | | | | | | In preparation for letting kerneldoc Sphinx extension to import Python libraries, move regex ancillary classes to a separate file. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/c76df228504e711c6b4bcd23d5a0ea1fda678cda.1744106241.git.mchehab+huawei@kernel.org
* scripts/kernel-doc.py: move regex methods to a separate fileMauro Carvalho Chehab2025-04-091-0/+272
In preparation for letting kerneldoc Sphinx extension to import Python libraries, move regex ancillary classes to a separate file. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/64f96b6744435b51894bb4ab7612851d9d054190.1744106241.git.mchehab+huawei@kernel.org
generated by cgit (git 2.51.2) at 2025-12-01 00:47:34 +0000