linux-kernel - [PATCH 0/9] docs: kdoc: rework the BODY* processing states

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: <20250621203512.223189-1-corbet@lwn.net>
Date: Sat, 21 Jun 2025 14:35:03 -0600
From: Jonathan Corbet <corbet@....net>
To: linux-doc@...r.kernel.org
Cc: linux-kernel@...r.kernel.org,
	Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
	Akira Yokosawa <akiyks@...il.com>,
	Jonathan Corbet <corbet@....net>
Subject: [PATCH 0/9] docs: kdoc: rework the BODY* processing states

This is a continuation of my effort to better understand the new kernel-doc
script and to clean up some of the legacy cruft brought over from the perl
version.

There were three states associated with the processing of the body of a
kerneldoc comment: BODY_MAYBE, BODY_WITH_BLANK_LINE, and BODY.
Unfortunately, these states did not actually match the state of the parser,
leading to a lot of deeply nested if-then-else code and special cases.
I've renamed the states to better reflect their meaning, and changed how
SPECIAL_SECTION, in particular, is managed.

  BODY_MAYBE becomes DECLARATION - we have seen the first line of the
  declaration that starts a kerneldoc comment, and don't know if we have
  hit the end of it or not.

  BODY_WITH_BLANK_LINE becomes SPECIAL_SECTION.  This state was used to
  recognize the sections within a comment with special rules -
  specifically, that the section ends with a blank line or the beginning of
  a new special section.  The declaration of parameters and sections like
  "Context" fit that description.  The old code recognized these sections
  at the *end*, with a lot of twisty logic; going into the proper state at
  the beginning simplifies things.  There are a few output changes, but I
  think they are all more correct.

  BODY remains BODY - a documentation section that does *not* end at a
  blank line.

To facilitate these changes, I have also begun the task of pulling more of
KernelEntry state management into the class itself; there is more to be
done on that front.

Jonathan Corbet (9):
  docs: kdoc: Make body_with_blank_line parsing more flexible
  docs: kdoc: consolidate the "begin section" logic
  docs: kdoc: separate out the handling of the declaration phase
  docs: kdoc: split out the special-section state
  docs: kdoc: coalesce the new-section handling
  docs: kdoc: rework the handling of SPECIAL_SECTION
  docs: kdoc: coalesce the end-of-comment processing
  docs: kdoc: Add some comments to process_decl()
  docs: kdoc: finish disentangling the BODY and SPECIAL_SECTION states

 scripts/lib/kdoc/kdoc_parser.py | 232 +++++++++++++++++++-------------
 1 file changed, 138 insertions(+), 94 deletions(-)

-- 
2.49.0