From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Linux Doc Mailing List <linux-doc@vger.kernel.org>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
linux-kernel@vger.kernel.org, Jonathan Corbet <corbet@lwn.net>,
Mauro Carvalho Chehab <mchehab@kernel.org>
Subject: [PATCH 10/13] docs: kdoc: parse_data_structs: Improve docstrings and comments
Date: Wed, 14 Jan 2026 14:17:23 +0100 [thread overview]
Message-ID: <6e009233720c331d51e0f6bbbf332410dd8f6da2.1768396023.git.mchehab+huawei@kernel.org> (raw)
In-Reply-To: <cover.1768396023.git.mchehab+huawei@kernel.org>
In preparation to document kernel-doc module, improve its
documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
tools/lib/python/kdoc/parse_data_structs.py | 62 +++++++++++++--------
1 file changed, 39 insertions(+), 23 deletions(-)
diff --git a/tools/lib/python/kdoc/parse_data_structs.py b/tools/lib/python/kdoc/parse_data_structs.py
index 25361996cd20..9941cd19032e 100755
--- a/tools/lib/python/kdoc/parse_data_structs.py
+++ b/tools/lib/python/kdoc/parse_data_structs.py
@@ -9,12 +9,12 @@ Parse a source file or header, creating ReStructured Text cross references.
It accepts an optional file to change the default symbol reference or to
suppress symbols from the output.
-It is capable of identifying defines, functions, structs, typedefs,
-enums and enum symbols and create cross-references for all of them.
+It is capable of identifying ``define``, function, ``struct``, ``typedef``,
+``enum`` and ``enum`` symbols and create cross-references for all of them.
It is also capable of distinguish #define used for specifying a Linux
ioctl.
-The optional rules file contains a set of rules like:
+The optional rules file contains a set of rules like::
ignore ioctl VIDIOC_ENUM_FMT
replace ioctl VIDIOC_DQBUF vidioc_qbuf
@@ -34,8 +34,8 @@ class ParseDataStructs:
It is meant to allow having a more comprehensive documentation, where
uAPI headers will create cross-reference links to the code.
- It is capable of identifying defines, functions, structs, typedefs,
- enums and enum symbols and create cross-references for all of them.
+ It is capable of identifying ``define``, function, ``struct``, ``typedef``,
+ ``enum`` and ``enum`` symbols and create cross-references for all of them.
It is also capable of distinguish #define used for specifying a Linux
ioctl.
@@ -43,13 +43,13 @@ class ParseDataStructs:
allows parsing an exception file. Such file contains a set of rules
using the syntax below:
- 1. Ignore rules:
+ 1. Ignore rules::
ignore <type> <symbol>`
Removes the symbol from reference generation.
- 2. Replace rules:
+ 2. Replace rules::
replace <type> <old_symbol> <new_reference>
@@ -58,22 +58,22 @@ class ParseDataStructs:
- A simple symbol name;
- A full Sphinx reference.
- 3. Namespace rules
+ 3. Namespace rules::
namespace <namespace>
Sets C namespace to be used during cross-reference generation. Can
be overridden by replace rules.
- On ignore and replace rules, <type> can be:
- - ioctl: for defines that end with _IO*, e.g. ioctl definitions
- - define: for other defines
- - symbol: for symbols defined within enums;
- - typedef: for typedefs;
- - enum: for the name of a non-anonymous enum;
- - struct: for structs.
+ On ignore and replace rules, ``<type>`` can be:
+ - ``ioctl``: for defines that end with ``_IO*``, e.g. ioctl definitions
+ - ``define``: for other defines
+ - ``symbol``: for symbols defined within enums;
+ - ``typedef``: for typedefs;
+ - ``enum``: for the name of a non-anonymous enum;
+ - ``struct``: for structs.
- Examples:
+ Examples::
ignore define __LINUX_MEDIA_H
ignore ioctl VIDIOC_ENUM_FMT
@@ -83,13 +83,15 @@ class ParseDataStructs:
namespace MC
"""
- # Parser regexes with multiple ways to capture enums and structs
+ #: Parser regex with multiple ways to capture enums.
RE_ENUMS = [
re.compile(r"^\s*enum\s+([\w_]+)\s*\{"),
re.compile(r"^\s*enum\s+([\w_]+)\s*$"),
re.compile(r"^\s*typedef\s*enum\s+([\w_]+)\s*\{"),
re.compile(r"^\s*typedef\s*enum\s+([\w_]+)\s*$"),
]
+
+ #: Parser regex with multiple ways to capture structs.
RE_STRUCTS = [
re.compile(r"^\s*struct\s+([_\w][\w\d_]+)\s*\{"),
re.compile(r"^\s*struct\s+([_\w][\w\d_]+)$"),
@@ -97,11 +99,13 @@ class ParseDataStructs:
re.compile(r"^\s*typedef\s*struct\s+([_\w][\w\d_]+)$"),
]
- # FIXME: the original code was written a long time before Sphinx C
+ # NOTE: the original code was written a long time before Sphinx C
# domain to have multiple namespaces. To avoid to much turn at the
# existing hyperlinks, the code kept using "c:type" instead of the
# right types. To change that, we need to change the types not only
# here, but also at the uAPI media documentation.
+
+ #: Dictionary containing C type identifiers to be transformed.
DEF_SYMBOL_TYPES = {
"ioctl": {
"prefix": "\\ ",
@@ -158,6 +162,10 @@ class ParseDataStructs:
self.symbols[symbol_type] = {}
def read_exceptions(self, fname: str):
+ """
+ Read an optional exceptions file, used to override defaults.
+ """
+
if not fname:
return
@@ -242,9 +250,9 @@ class ParseDataStructs:
def store_type(self, ln, symbol_type: str, symbol: str,
ref_name: str = None, replace_underscores: bool = True):
"""
- Stores a new symbol at self.symbols under symbol_type.
+ Store a new symbol at self.symbols under symbol_type.
- By default, underscores are replaced by "-"
+ By default, underscores are replaced by ``-``.
"""
defs = self.DEF_SYMBOL_TYPES[symbol_type]
@@ -276,12 +284,16 @@ class ParseDataStructs:
self.symbols[symbol_type][symbol] = (f"{prefix}{ref_link}{suffix}", ln)
def store_line(self, line):
- """Stores a line at self.data, properly indented"""
+ """
+ Store a line at self.data, properly indented.
+ """
line = " " + line.expandtabs()
self.data += line.rstrip(" ")
def parse_file(self, file_in: str, exceptions: str = None):
- """Reads a C source file and get identifiers"""
+ """
+ Read a C source file and get identifiers.
+ """
self.data = ""
is_enum = False
is_comment = False
@@ -433,7 +445,7 @@ class ParseDataStructs:
def gen_toc(self):
"""
- Create a list of symbols to be part of a TOC contents table
+ Create a list of symbols to be part of a TOC contents table.
"""
text = []
@@ -464,6 +476,10 @@ class ParseDataStructs:
return "\n".join(text)
def write_output(self, file_in: str, file_out: str, toc: bool):
+ """
+ Write a ReST output file.
+ """
+
title = os.path.basename(file_in)
if toc:
--
2.52.0
next prev parent reply other threads:[~2026-01-14 13:17 UTC|newest]
Thread overview: 23+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-01-14 13:17 [PATCH 00/13] Add kernel-doc modules to Documentation/tools Mauro Carvalho Chehab
2026-01-14 13:17 ` [PATCH 01/13] docs: custom.css: prevent li marker to override text Mauro Carvalho Chehab
2026-01-14 13:17 ` [PATCH 02/13] docs: enable Sphinx autodoc extension to allow documenting python Mauro Carvalho Chehab
2026-01-15 10:19 ` Jani Nikula
2026-01-15 11:50 ` Mauro Carvalho Chehab
2026-01-15 12:18 ` Jani Nikula
2026-01-15 12:57 ` Mauro Carvalho Chehab
2026-01-14 13:17 ` [PATCH 03/13] docs: custom.css: add CSS for python Mauro Carvalho Chehab
2026-01-14 13:17 ` [PATCH 04/13] docs: kdoc: latex_fonts: Improve docstrings and comments Mauro Carvalho Chehab
2026-01-14 13:17 ` [PATCH 05/13] docs: kdoc_files: " Mauro Carvalho Chehab
2026-01-14 13:17 ` [PATCH 06/13] docs: kdoc_item: " Mauro Carvalho Chehab
2026-01-14 13:17 ` [PATCH 07/13] docs: kdoc_parser: " Mauro Carvalho Chehab
2026-01-14 13:17 ` [PATCH 08/13] docs: kdoc_output: " Mauro Carvalho Chehab
2026-01-14 13:17 ` [PATCH 09/13] docs: kdoc_re: " Mauro Carvalho Chehab
2026-01-14 13:17 ` Mauro Carvalho Chehab [this message]
2026-01-14 13:17 ` [PATCH 11/13] docs: kdoc: enrich_formatter: " Mauro Carvalho Chehab
2026-01-14 13:17 ` [PATCH 12/13] docs: kdoc: python_version: " Mauro Carvalho Chehab
2026-01-14 13:17 ` [PATCH 13/13] docs: add kernel-doc modules documentation Mauro Carvalho Chehab
2026-01-14 18:01 ` [PATCH 00/13] Add kernel-doc modules to Documentation/tools Jonathan Corbet
2026-01-14 20:20 ` Mauro Carvalho Chehab
2026-01-14 20:46 ` Jonathan Corbet
2026-01-15 1:29 ` Mauro Carvalho Chehab
2026-01-15 10:17 ` Mauro Carvalho Chehab
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=6e009233720c331d51e0f6bbbf332410dd8f6da2.1768396023.git.mchehab+huawei@kernel.org \
--to=mchehab+huawei@kernel.org \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=mchehab@kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
all inboxes | Powered by JetHome®