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

[Jonathan Corbet]

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