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
