mirrors/linux
1
0
Fork 0
mirror of https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git synced 2026-05-04 10:56:06 -04:00
Code Issues Packages Projects Releases Wiki Activity
1,351,160 Commits 1 Branch 929 Tags
5c5c32d7abd970f18ffca89eb6ada399bce496e5
Commit Graph

1351160 Commits

This Branch
This Branch
All Branches
Author SHA1 Message Date
Mauro Carvalho Chehab
5c5c32d7ab scripts/kernel-doc.py: don't create *.pyc files 
As reported by Andy, kernel-doc.py is creating a __pycache__
directory at build time.

Disable creation of __pycache__ for the libraries used by
kernel-doc.py, when excecuted via the build system or via
scripts/find-unused-docs.sh.

Reported-by: Andy Shevchenko <andriy.shevchenko@intel.com>
Closes: https://lore.kernel.org/linux-doc/Z_zYXAJcTD-c3xTe@black.fi.intel.com/
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Tested-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <158b962ed7cd104f7bbfe69f499ec1cc378864db.1745453655.git.mchehab+huawei@kernel.org>
 2025-04-24 10:12:46 -06:00
Mauro Carvalho Chehab
110214e4cc Makefile: move KERNELDOC macro to the main Makefile 
As kernel-doc script is used not only on Documentation, but
also on scripts and drivers/drm Makefiles, move it to the
main makefile, as otherwise sub-makefiles may not have it.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Tested-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <bb3ea3b49e76aee51dae7762db10c4d38cd67afe.1745453655.git.mchehab+huawei@kernel.org>
 2025-04-24 10:12:46 -06:00
Mauro Carvalho Chehab
76a9b59228 docs: Makefile: get rid of KERNELDOC_CONF env variable 
Despite its name, what's there is a set of Sphinx arguments that
are passed to sphinx/kerneldoc.py:

- kerneldoc_srctree: location of the source tree;
- kerneldoc_bin: external script to excecute kernel-doc

Drop it, and just place the values at the already-existing
ALLSPHINXOPTS variable.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Tested-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <88be0fc288598c30fbedb9cc230b2a7ed28225a2.1745453655.git.mchehab+huawei@kernel.org>
 2025-04-24 10:12:46 -06:00
Mauro Carvalho Chehab
9d9bec3d90 docs: sphinx: kerneldoc: Use python class if available 
Better integrate with the new kernel-doc tool by calling the
Python classes directly if KERNELDOC=scripts/kernel-doc.py.

This way, warnings won't be duplicated anymore, as files
will be parsed only once.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/1556a6c005d8e0fafa951f74725e984e1c7459bf.1744685912.git.mchehab+huawei@kernel.org
 2025-04-21 10:39:18 -06:00
Mauro Carvalho Chehab
47c2d4168b 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
 2025-04-21 10:39:17 -06:00
Mauro Carvalho Chehab
f9cdbc5781 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
 2025-04-21 10:39:17 -06:00
Mauro Carvalho Chehab
439111ee0c scripts/lib/kdoc/kdoc_files.py: don't try to join None 
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 <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/4334d16f14cfd93e611b290fb56c35d236cadcb7.1744685912.git.mchehab+huawei@kernel.org
 2025-04-21 10:39:17 -06:00
Purva Yeshi
f0ba72e655 Documentation: trace: Refactor toctree 
Refactor table of contents of kernel tracing subsystem docs to improve
clarity, structure, and organization:

- Reformat sections and add appropriate headings
- Improve section grouping and refine descriptions for each group
- Add docs intro paragraph

Signed-off-by: Purva Yeshi <purvayeshi550@gmail.com>
Link: https://lore.kernel.org/r/20250318113230.24950-2-purvayeshi550@gmail.com
[Bagas: massage commit message and address reviews]
Co-developed-by: Bagas Sanjaya <bagasdotme@gmail.com>
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
Acked-by: Steven Rostedt (Google) <rostedt@goodmis.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
 2025-04-21 10:37:13 -06:00
Purva Yeshi
33583537dd Documentation: trace: Reduce toctree depth 
Reduce toctree depth from 2 to 1 so that only docs titles are listed
in the toctree.

Signed-off-by: Purva Yeshi <purvayeshi550@gmail.com>
Link: https://lore.kernel.org/r/20250318113230.24950-1-purvayeshi550@gmail.com
[Bagas: massage commit message]
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
Acked-by: Steven Rostedt (Google) <rostedt@goodmis.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
 2025-04-21 10:37:01 -06:00
Ammar Askar
43e9076a00 docs: Fix conflicting contributor identity info 
In commit d4563201f3 ("Documentation: simplify and clarify DCO
contribution example language"), the patch submission documentation was
updated to remove the note about pseudonyms and instead simplify it to
allow "known identities".

The process documentation still explicitly prohibits pseudonymous
contributors. This patch changes the process documentation to line up
with the submitting patches document.

Signed-off-by: Ammar Askar <ammar@ammaraskar.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250318235331.3566174-1-ammar@ammaraskar.com
 2025-04-14 10:46:41 -06:00
Andres Urian Florez
960c7d6787 docs/sp_SP: fix links to mailing list services 
With the changes in the way mailing lists are hostet at kernel.org, there
is a need to sync the Spanish documentation to:

1. fix links that are pointing at the outdated resources
2. remove an outdated patchbomb admonition

Signed-off-by: Andres Urian Florez <andres.emb.sys@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250324164613.12639-1-andres.emb.sys@gmail.com
 2025-04-14 10:44:52 -06:00
Tomas Glozar
770840a0e7 Documentation/rtla: Include BPF sample collection 
Add dependencies needed to build rtla with BPF sample collection support
to README, and document both ways of sample collection in the manpages.

Signed-off-by: Tomas Glozar <tglozar@redhat.com>
Acked-by: Steven Rostedt (Google) <rostedt@goodmis.org>
Reviewed-by: Luis Claudio R. Goncalves <lgoncalv@redhat.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250311114936.148012-5-tglozar@redhat.com
 2025-04-14 10:42:55 -06:00
Tomas Glozar
e7d3b24e34 Documentation/rtla: Fix typo in common_timerlat_description.rst 
Fix "it enable" to "it enables".

Fixes: 29380d4055 ("rtla: Add rtla timerlat documentation")
Signed-off-by: Tomas Glozar <tglozar@redhat.com>
Reviewed-by: Luis Claudio R. Goncalves <lgoncalv@redhat.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250311114936.148012-4-tglozar@redhat.com
 2025-04-14 10:42:55 -06:00
Tomas Glozar
caa42c6df3 Documentation/rtla: Fix typo in rtla-timerlat.rst 
The file says "rtla hist hist mode" instead of "rtla timerlat hist
mode".

Fix the typo.

Fixes: 29380d4055 ("rtla: Add rtla timerlat documentation")
Signed-off-by: Tomas Glozar <tglozar@redhat.com>
Reviewed-by: Luis Claudio R. Goncalves <lgoncalv@redhat.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250311114936.148012-3-tglozar@redhat.com
 2025-04-14 10:42:55 -06:00
Tomas Glozar
0cc9e7cae3 Documentation/rtla: Fix duplicate text about timerlat tracer 
A passage about how the timerlat tracer outputs information is included
in both common_timerlat_description.rst and rtla-timerlat.rst, leading
it to be displayed twice in the rtla-timerlat page.

Remove the duplicate passage from rtla-timerlat.rst.

Fixes: 29380d4055 ("rtla: Add rtla timerlat documentation")
Signed-off-by: Tomas Glozar <tglozar@redhat.com>
Reviewed-by: Luis Claudio R. Goncalves <lgoncalv@redhat.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250311114936.148012-2-tglozar@redhat.com
 2025-04-14 10:42:55 -06:00
Chih Yun Lin
1af310951e docs: hid: Fix typo in intel-thc-hid.rst 
Corrected the spelling of "triggerred" to "triggered" and "flexiblity"
to "flexibility".

Signed-off-by: Chih Yun Lin <noralin249@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250330084518.20916-1-noralin249@gmail.com
 2025-04-14 10:40:52 -06:00
Kevin Paul Reddy Janagari
dd0808ab40 Added usb_string function to a namespace 
with reference to WARNING:
Duplicate C declaration, also defined at driver-api/usb/gadget:804
There is a function usb_string in the file message.c,
there is also a struct usb_string in the kernel api headers.
The docs is unable to index the function as the index is occupied by struct
This fix adds messgae.c to the usb_core namespace (in docs) hence providing
usb_sting a unique index usb_core.usb_string()

Signed-off-by: Kevin Paul Reddy Janagari <kevinpaul468@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250405165116.147958-1-kevinpaul468@gmail.com
 2025-04-14 10:35:44 -06:00
Randy Dunlap
e54ac58667 cpufreq: editing corrections to cpufreq.rst 
Change a few words and abbreviations/punctuation.

Change one echo command to include a trailing '`'.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Rafael J. Wysocki <rafael@kernel.org>
Cc: Viresh Kumar <viresh.kumar@linaro.org>
Cc: linux-pm@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250405001447.4039463-1-rdunlap@infradead.org
 2025-04-14 10:29:32 -06:00
James Addison
3fa3b20ba1 docs: Disambiguate a pair of rST labels 
According to the reStructuredText documentation, internal hyperlink
targets[1] are intended to resolve within the current document.

Sphinx has a bug that causes internal hyperlinks declared with
duplicate names to resolve nondeterministically, producing incorrect
documentation. Sphinx does not yet emit a warning when these
duplicate target names are declared.

To improve the reproducibility and correctness of the HTML
documentation, disambiguate two labels both previously titled
"submit_improvements".

[1] - https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#hyperlink-targets

Link: https://github.com/sphinx-doc/sphinx/issues/13383
Signed-off-by: James Addison <jay@jp-hosting.net>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250407195120.331103-2-jvanderwaa@redhat.com
 2025-04-14 10:22:46 -06:00
Nícolas F. R. A. Prado
fb42d8dcbc docs: automarkup: Move common logic to add and resolve xref to helper 
Several of the markup functions contain the same code, calling into
sphinx's pending_xref and resolve_xref functions to add and resolve a
cross-reference, with only a few of the parameters changed (domain,
reference type, markup content). Move this logic to its own function and
reuse it in the markup functions.

No functional change.

Signed-off-by: Nícolas F. R. A. Prado <nfraprado@collabora.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250408-automarkup-resolve-xref-helper-v2-1-e0a9b8fc7fdd@collabora.com
 2025-04-14 10:04:07 -06:00
Jonathan Corbet
9f488ccd0f Merge branch 'mauro' into docs-mw 
Mauro says:

This changeset contains the kernel-doc.py script to replace the verable
kernel-doc originally written in Perl. It replaces the first version and the
second series I sent on the top of it.

I tried to stay as close as possible of the original Perl implementation
on the first patch introducing kernel-doc.py, as it helps to double check
if each function was  properly translated to Python.  This have been
helpful debugging troubles that happened during the conversion.

I worked hard to make it bug-compatible with the original one. Still, its
output has a couple of differences from the original one:

- The tab expansion works better with the Python script. With that, some
  outputs that contain tabs at kernel-doc markups are now different;

- The new script  works better stripping blank lines. So, there are a couple
  of empty new lines that are now stripped with this version;

- There is a buggy logic at kernel-doc to strip empty description and
  return sections. I was not able to replicate the exact behavior. So, I ended
  adding an extra logic to strip empty sections with a different algorithm.

Yet, on my tests, the results are compatible with the venerable script
output for all .. kernel-doc tags found in Documentation/. I double-checked
this by adding support to output the kernel-doc commands when V=1, and
then I ran a diff between kernel-doc.pl and kernel-doc.py for the same
command lines.

The only patch that doesn't belong to this series is a patch dropping
kernel-doc.pl. I opted to keep it for now, as it can help to better
test the new tools.

With such changes, if one wants to build docs with the old script,
all it is needed is to use KERNELDOC parameter, e.g.:

	$ make KERNELDOC=scripts/kernel-doc.pl htmldocs
 2025-04-09 12:24:51 -06:00
Sean Anderson
de258fa8ca 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: 7d2c6b1edf ("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
 2025-04-09 12:10:34 -06:00
Mauro Carvalho Chehab
04a383ced6 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
 2025-04-09 12:10:34 -06:00
Mauro Carvalho Chehab
16740c29db 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
 2025-04-09 12:10:34 -06:00
Mauro Carvalho Chehab
a566ba5af5 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
 2025-04-09 12:10:34 -06:00
Mauro Carvalho Chehab
fc862949a3 scripts/kernel-doc: switch to use kernel-doc.py 
Now that all features are in place, change the kernel-doc alias
to point to kernel-doc.py.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/d84a2ad282821928a60b8dcbec305ef7e7bd58e6.1744106242.git.mchehab+huawei@kernel.org
 2025-04-09 12:10:34 -06:00
Mauro Carvalho Chehab
11afeab6d7 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
 2025-04-09 12:10:34 -06:00
Mauro Carvalho Chehab
e4b2bd908c 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
 2025-04-09 12:10:34 -06:00
Mauro Carvalho Chehab
91d00bd54f scripts/kernel-doc.py: properly handle KBUILD_BUILD_TIMESTAMP 
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 <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/ffc70a1b741b010365ed82f31611018f24f91ce7.1744106242.git.mchehab+huawei@kernel.org
 2025-04-09 12:10:34 -06:00
Mauro Carvalho Chehab
2ab867a494 scripts/kernel-doc.py: move modulename to man class 
Only man output requires a modulename. Move its definition
to the man 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/583085e3885b0075d16ef9961b4f2ad870f30a55.1744106242.git.mchehab+huawei@kernel.org
 2025-04-09 12:10:34 -06:00
Mauro Carvalho Chehab
78ea748f79 scripts/lib/kdoc/kdoc_parser.py: fix Python compat with < v3.13 
- 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 <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/e2b8e8361294558dae09236e4b8fbea5d86be5a3.1744106242.git.mchehab+huawei@kernel.org
 2025-04-09 12:10:34 -06:00
Mauro Carvalho Chehab
485f6f7960 scripts/kernel-doc.py: adjust some coding style issues 
Make pylint happier by adding some missing documentation and
addressing a couple of pylint warnings.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/0f9d5473105e4c09c6c41e3db72cc63f1d4d55f9.1744106242.git.mchehab+huawei@kernel.org
 2025-04-09 12:10:34 -06:00
Mauro Carvalho Chehab
43ecfe6bc2 scripts/kernel-doc.py: Set an output format for --none 
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 <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/caa1089e16f4609f792ff26731ad9e9c3a6f6b1d.1744106242.git.mchehab+huawei@kernel.org
 2025-04-09 12:10:34 -06:00
Mauro Carvalho Chehab
feec610725 docs: sphinx: kerneldoc: use kernel-doc.py script 
Switch to the new version when producing documentation.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/a81d8db099d9cef5161deaef40ac9056bf9802a3.1744106242.git.mchehab+huawei@kernel.org
 2025-04-09 12:10:34 -06:00
Mauro Carvalho Chehab
01c4335525 docs: sphinx: kerneldoc: ignore "\" characters from options 
Documentation/driver-api/infiniband.rst has a kernel-doc tag
with "\" characters at the end:

	.. kernel-doc:: drivers/infiniband/ulp/iser/iscsi_iser.c
	   :functions: iscsi_iser_pdu_alloc iser_initialize_task_headers \
	        iscsi_iser_task_init iscsi_iser_mtask_xmit iscsi_iser_task_xmit \
	        iscsi_iser_cleanup_task iscsi_iser_check_protection \
	        iscsi_iser_conn_create iscsi_iser_conn_bind \
	        iscsi_iser_conn_start iscsi_iser_conn_stop \
	        iscsi_iser_session_destroy iscsi_iser_session_create \
	        iscsi_iser_set_param iscsi_iser_ep_connect iscsi_iser_ep_poll \
	        iscsi_iser_ep_disconnect

This is not handled well, as the "\" strings will be just stored inside
Sphinx options.

While the actual problem deserves being fixed, better to relax the
keneldoc.py extension to silently strip "\" from the end of strings,
as otherwise this may cause troubles when preparing arguments to
be executed by kernel-doc.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/4c652d6c57b20500c135b95294e554d9e9a97f42.1744106242.git.mchehab+huawei@kernel.org
 2025-04-09 12:10:33 -06:00
Mauro Carvalho Chehab
668b9d1dce docs: sphinx: kerneldoc: verbose kernel-doc command if V=1 
It is useful to know what kernel-doc command was used during
document build time, as it allows one to check the output the same
way as Sphinx extension does.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/a2f01590814b111e138f278e8a721024fdf2d445.1744106242.git.mchehab+huawei@kernel.org
 2025-04-09 12:10:33 -06:00
Mauro Carvalho Chehab
02df8e3b33 docs: add a .pylintrc file with sys path for docs scripts 
The docs scripts that are used by Documentation/sphinx are
using scripts/lib/* directories to place classes that will
be used by both extensions and scripts.

When pylint is used, it needs to identify the path where
such scripts are, otherwise it will bail out. Add a simple
RC file placing the location of such files.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/7b3c8a932c50ae52ce4c848676602b46d1d4a8f9.1744106242.git.mchehab+huawei@kernel.org
 2025-04-09 12:10:33 -06:00
Mauro Carvalho Chehab
9cbc2d3b13 scripts/kernel-doc.py: postpone warnings to the output plugin 
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 <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/e6344711e390cf22af02a56bb5dd51ca67c0afb6.1744106242.git.mchehab+huawei@kernel.org
 2025-04-09 12:10:33 -06:00
Mauro Carvalho Chehab
9235ec5e2b scripts/kernel-doc.py: properly handle out_section for ReST 
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 <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/935d00c6a7c45b25a8be72fad6183fe5a8476cd2.1744106242.git.mchehab+huawei@kernel.org
 2025-04-09 12:10:33 -06:00
Mauro Carvalho Chehab
408269ae35 scripts/kernel-doc.py: fix handling of doc output check 
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 <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/6d8b77af85295452c0191863ea1041f4195aeaaf.1744106242.git.mchehab+huawei@kernel.org
 2025-04-09 12:10:33 -06:00
Mauro Carvalho Chehab
c3597ab27b scripts/kernel-doc.py: fix line number output 
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 <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/5182a531d14b5fe9e1fc5da5f9dae05d66852a60.1744106242.git.mchehab+huawei@kernel.org
 2025-04-09 12:10:33 -06:00
Mauro Carvalho Chehab
0873e55433 scripts/kernel-doc.py: implement support for -no-doc-sections 
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 <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/06b18a32142b44d5ba8b41ac64a76c02b03b4969.1744106242.git.mchehab+huawei@kernel.org
 2025-04-09 12:10:33 -06:00
Mauro Carvalho Chehab
799b0d2a2a scripts/kernel-doc.py: move file lists to the parser function 
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 <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/ab10bc94050406ce6536d4944b5d718ecd70812f.1744106242.git.mchehab+huawei@kernel.org
 2025-04-09 12:10:33 -06:00
Mauro Carvalho Chehab
4fa5e41137 scripts/kernel-doc.py: convert message output to an interactor 
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 <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/557304c8458f1fb4aa2e833f4bdaff953094ddcb.1744106242.git.mchehab+huawei@kernel.org
 2025-04-09 12:10:33 -06:00
Mauro Carvalho Chehab
1d6fea640e scripts/kernel-doc.py: move output classes to a separate file 
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 <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/81087eff25d11c265019a8631f7fc8d3904795d0.1744106242.git.mchehab+huawei@kernel.org
 2025-04-09 12:10:33 -06:00
Mauro Carvalho Chehab
ee13b3f35c scripts/kernel-doc.py: move KernelFiles class to a separate file 
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 <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/80bc855e128a9ff0a11df5afe9ba71775dfc9a0f.1744106241.git.mchehab+huawei@kernel.org
 2025-04-09 12:10:33 -06:00
Mauro Carvalho Chehab
d966dc658c scripts/kernel-doc.py: move KernelDoc class to a separate 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 <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/c76df228504e711c6b4bcd23d5a0ea1fda678cda.1744106241.git.mchehab+huawei@kernel.org
 2025-04-09 12:10:33 -06:00
Mauro Carvalho Chehab
e31fd36da9 scripts/kernel-doc.py: move regex methods to a separate 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 <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/64f96b6744435b51894bb4ab7612851d9d054190.1744106241.git.mchehab+huawei@kernel.org
 2025-04-09 12:10:33 -06:00
Mauro Carvalho Chehab
01d3235dde scripts/kernel-doc.py: properly handle struct_group macros 
Handing nested parenthesis with regular expressions is not an
easy task. It is even harder with Python's re module, as it
has a limited subset of regular expressions, missing more
advanced features.

We might use instead Python regex module, but still the
regular expressions are very hard to understand. So, instead,
add a logic to properly match delimiters.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/74dee485f70b7ce85e90496bfdd360283a677a58.1744106241.git.mchehab+huawei@kernel.org
 2025-04-09 12:10:33 -06:00
Mauro Carvalho Chehab
3592385668 scripts/kernel-doc.py: better handle empty sections 
While doing the conversion, we opted to skip empty sections
(description, return), but this makes harder to see the differences
between kernel-doc (Perl) and kernel-doc.py.

Also, the logic doesn't always work properly. So, change the
way this is done by adding an extra step to remove such
sections, doing it only for Return and Description.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/1b057092a48ba61d92a411f4f6d505b802913785.1744106241.git.mchehab+huawei@kernel.org
 2025-04-09 12:10:32 -06:00