linux-kernel - [PATCH v7 0/6] kernel-doc: add support for documenting vars

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Message-ID: <cover.1765894964.git.mchehab+huawei@kernel.org>
Date: Tue, 16 Dec 2025 15:26:11 +0100
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Linux Doc Mailing List <linux-doc@...r.kernel.org>,
	Jonathan Corbet <corbet@....net>
Cc: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
	linux-kernel@...r.kernel.org,
	Randy Dunlap <rdunlap@...radead.org>
Subject: [PATCH v7 0/6] kernel-doc: add support for documenting vars

Hi Jon,

Please ignore v6. I ended adding a R-B at patch 6 instead of on patch 5.

As suggested and discussed with Randy, this small series add support
for documenting variables using kernel-doc.

- patch 1: add support for the new feature;
- patch 2: extends to support DEFINE_*;
- patch 3: document two media vars;
- patch 4: fix an issue on kernel-doc.rst markups and automarkup;
- patch 5: document it;
- patch 6: better handle DEFINE_ macros when they don't have static/type;

Since version 5, I'm using "c:macro" to describe variables, as it
avoids Sphinx C domain to try parse the variable. This makes it more
flexible and easier to maintain in long term.

---

v7:
- fixed a reviewed-by: it should be at patch 5, not 6.

v6:
- added patch 6

v5:
- use ``foo`` for prototype and on patch 3.

v4: 
- document the new markup;
- fix an issue on kernel-doc.rst due to automarkup;
- add support for DEFINE_* macros

Mauro Carvalho Chehab (6):
  kernel-doc: add support for handling global variables
  kernel-doc: add support to handle DEFINE_ variables
  docs: media: v4l2-ioctl.h: document two global variables
  docs: kernel-doc.rst: don't let automarkup mangle with consts
  docs: kernel-doc.rst: document the new "var" kernel-doc markup
  docs: kernel-doc.rst: Parse DEFINE_ macros without prefixes

 Documentation/doc-guide/kernel-doc.rst | 48 +++++++++++-----
 include/media/v4l2-ioctl.h             | 15 +++++
 tools/lib/python/kdoc/kdoc_output.py   | 46 +++++++++++++++
 tools/lib/python/kdoc/kdoc_parser.py   | 79 +++++++++++++++++++++++++-
 4 files changed, 172 insertions(+), 16 deletions(-)

-- 
2.52.0