From nobody Mon Feb 9 03:14:28 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 6A3E829B228; Mon, 19 Jan 2026 16:23:34 +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=1768839814; cv=none; b=QkX9/LQnZosxYtCvlB6tHFCGz53tDNM12jtrrwrCm81sM1c0wfi0q0zfjHYrKniZ22+LNtIBoUak5Xt78oG9igDcQkZFd+0+WVBawjeVrecp/oe9JrDlZUnUc/nKCUL1vRPDnknx5ijbjkyVPz4u09GkaU+AqvOfdjcj6NiCb88= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768839814; c=relaxed/simple; bh=i1tcZCaxJM2MU0fiO/S47vsflPzYkddGYteNjd18qHw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=d4bJ3AzBXlTI6sNfLK9SMrkWHEtPUb/MY0cfGHwblS+8LBL71rLeyB2whfBKYm954zhPExg26hu88haCkz4BZd+Ah+dzmIuNcyuEaQXXse5lzO+/vIS+pUf0Yw+iz32He1gzhHsUmqIxNCM1qzrcA/0M3chxjpMUaplAKgaT96Q= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=d69NExac; 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="d69NExac" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 1D492C19425; Mon, 19 Jan 2026 16:23:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768839814; bh=i1tcZCaxJM2MU0fiO/S47vsflPzYkddGYteNjd18qHw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=d69NExacPxZ0Dv/g9MXpuB8KNYqUbDaN/faj7Wuh3UBiYZkvNsq3rwp7dtMGL8zKj 3R5e9F5pdNcLGxxJPFW1EHdKeC+YrRgnT2YynPkBqGLZ60oQ0ovfIgDBJb8NrDMCGk chmcPegiSt77KiLWRrxabNZBYpQgLDPS20oRUgW9lxgs4dR0x2qrztFUJn/eNELEb3 Ez1I+u2AEKONFm6NYLPPKcebHU+q2ckAuv4FGuK9FFXKnxMWgzuenX3E9mMe1y0AIp eJeca9oMxCExCqN1VAPsJuO9d9RuUBlLbq2qzipQWlng4LSXaoELeUGP4o9W6G7f6x 1jIYmGjTD1TXA== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vhs2O-00000001j28-1gfC; Mon, 19 Jan 2026 17:23:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab Subject: [PATCH 12/25] docs: kdoc: parse_data_structs: Improve docstrings and comments Date: Mon, 19 Jan 2026 17:23:15 +0100 Message-ID: <76ead85b4c13a8038180a792e270c3691d26cd25.1768838938.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