From nobody Mon Feb 9 09:28:54 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 7D9C53AA1AA; Thu, 15 Jan 2026 15:40:42 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768491642; cv=none; b=RmssOi6uhMpNfZFyTapZ70d7maUsZYyEKqSCCtJg3O5txx4EiHzXTLoE+1iU9P6JhB8iiIfP301SmNCyfkrh6UglLXimj7zs8U8xo2PZIiMnGiZYBZ6+fFLS8OUWWR8XZ2gpj0LitPIcIyRqzfiJEVn1voqnU8mFG/hHdKj7/mA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768491642; c=relaxed/simple; bh=i1tcZCaxJM2MU0fiO/S47vsflPzYkddGYteNjd18qHw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=ncINNDZIxyyvFzFbCDyvNHd5L4SZ2VM7ibBue6FZCg4aGpDUDGS+w96WJ48pgp5A2a9w71RvMdpbg4l9mpC7YI9MCISANzjeQkhik4jVSc7u1+nJPYEWswQ/at30Gok8z8/4tRgHUbbHPkayVG/e0S8792aSYRd924WW61ED9Qs= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=G96KHlOd; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="G96KHlOd" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 22136C2BCB1; Thu, 15 Jan 2026 15:40:42 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768491642; bh=i1tcZCaxJM2MU0fiO/S47vsflPzYkddGYteNjd18qHw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=G96KHlOdkwqcE7M0bta2YtY+/0hCe4qQtNb8PMvha3wAvXEm+6sGE2eJ7y88RkDx2 rjNHwkidXUnol4368x87s6mPp0tVY/Pvcsp7JxR00Oaq12MW2CzZHM985jjiao3R7z e/u4AMH8jJ4l5Vkbq3yDJls85ElfMVBnq2sjC7634a8iK7A9J6cOasX3mCiJAPrEdd Wbgdqs755Xn5IKQUy72+QqyC/wnEykPIe1NffDNvA9OSl166EaGCTvvClRY+HYuyeU gRofAvM23PyNhzJIKMS4TTo1/J90lojHlv6UL/ET+GwOkTtaqEvdUbgAdoexrLw3L6 tjsyVBWTPfKOw== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vgPSi-000000043It-1jAP; Thu, 15 Jan 2026 16:40:40 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , Mauro Carvalho Chehab Subject: [PATCH v2 12/15] docs: kdoc: parse_data_structs: Improve docstrings and comments Date: Thu, 15 Jan 2026 16:40:33 +0100 Message-ID: <6a613960686d6ff0377f7365f7f547c31d487593.1768488832.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab In preparation to document kernel-doc module, improve its documentation. Signed-off-by: Mauro Carvalho Chehab --- 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. =20 -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. =20 -The optional rules file contains a set of rules like: +The optional rules file contains a set of rules like:: =20 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. =20 - 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``, ``typed= ef``, + ``enum`` and ``enum`` symbols and create cross-references for all of t= hem. It is also capable of distinguish #define used for specifying a Linux ioctl. =20 @@ -43,13 +43,13 @@ class ParseDataStructs: allows parsing an exception file. Such file contains a set of rules using the syntax below: =20 - 1. Ignore rules: + 1. Ignore rules:: =20 ignore ` =20 Removes the symbol from reference generation. =20 - 2. Replace rules: + 2. Replace rules:: =20 replace =20 @@ -58,22 +58,22 @@ class ParseDataStructs: - A simple symbol name; - A full Sphinx reference. =20 - 3. Namespace rules + 3. Namespace rules:: =20 namespace =20 Sets C namespace to be used during cross-reference generation. Can be overridden by replace rules. =20 - On ignore and replace rules, 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, ```` can be: + - ``ioctl``: for defines that end with ``_IO*``, e.g. ioctl defini= tions + - ``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. =20 - Examples: + Examples:: =20 ignore define __LINUX_MEDIA_H ignore ioctl VIDIOC_ENUM_FMT @@ -83,13 +83,15 @@ class ParseDataStructs: namespace MC """ =20 - # Parser regexes with multiple ways to capture enums and structs + #: Parser regex with multiple ways to capture enums. RE_ENUMS =3D [ 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 =3D [ 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_]+)$"), ] =20 - # 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 =3D { "ioctl": { "prefix": "\\ ", @@ -158,6 +162,10 @@ class ParseDataStructs: self.symbols[symbol_type] =3D {} =20 def read_exceptions(self, fname: str): + """ + Read an optional exceptions file, used to override defaults. + """ + if not fname: return =20 @@ -242,9 +250,9 @@ class ParseDataStructs: def store_type(self, ln, symbol_type: str, symbol: str, ref_name: str =3D None, replace_underscores: bool =3D T= rue): """ - Stores a new symbol at self.symbols under symbol_type. + Store a new symbol at self.symbols under symbol_type. =20 - By default, underscores are replaced by "-" + By default, underscores are replaced by ``-``. """ defs =3D self.DEF_SYMBOL_TYPES[symbol_type] =20 @@ -276,12 +284,16 @@ class ParseDataStructs: self.symbols[symbol_type][symbol] =3D (f"{prefix}{ref_link}{suffix= }", ln) =20 def store_line(self, line): - """Stores a line at self.data, properly indented""" + """ + Store a line at self.data, properly indented. + """ line =3D " " + line.expandtabs() self.data +=3D line.rstrip(" ") =20 def parse_file(self, file_in: str, exceptions: str =3D None): - """Reads a C source file and get identifiers""" + """ + Read a C source file and get identifiers. + """ self.data =3D "" is_enum =3D False is_comment =3D False @@ -433,7 +445,7 @@ class ParseDataStructs: =20 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 =3D [] =20 @@ -464,6 +476,10 @@ class ParseDataStructs: return "\n".join(text) =20 def write_output(self, file_in: str, file_out: str, toc: bool): + """ + Write a ReST output file. + """ + title =3D os.path.basename(file_in) =20 if toc: --=20 2.52.0