Commit 35923856 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Jonathan Corbet
Browse files

scripts/kernel-doc.py: better handle empty sections 



While doing the conversion, we opted to skip empty sections
(description, return), but this makes harder to see the differences
between kernel-doc (Perl) and kernel-doc.py.

Also, the logic doesn't always work properly. So, change the
way this is done by adding an extra step to remove such
sections, doing it only for Return and Description.

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/1b057092a48ba61d92a411f4f6d505b802913785.1744106241.git.mchehab+huawei@kernel.org
parent 0a4e2412

scripts/kernel-doc.py

+28 −3
Original line number Diff line number Diff line
@@ -317,6 +317,19 @@ class KernelDoc: 
        name = self.entry.section

        contents = self.entry.contents



        # TODO: we can prevent dumping empty sections here with:

        #

        #    if self.entry.contents.strip("\n"):

        #       if start_new:

        #           self.entry.section = self.section_default

        #           self.entry.contents = ""

        #

        #        return

        #

        # But, as we want to be producing the same output of the

        # venerable kernel-doc Perl tool, let's just output everything,

        # at least for now



        if type_param.match(name):

            name = type_param.group(1)
@@ -373,6 +386,19 @@ class KernelDoc: 


        args["type"] = dtype



        # TODO: use colletions.OrderedDict



        sections = args.get('sections', {})

        sectionlist = args.get('sectionlist', [])



        # Drop empty sections

        # TODO: improve it to emit warnings

        for section in [ "Description", "Return" ]:

            if section in sectionlist:

                if not sections[section].rstrip():

                    del sections[section]

                    sectionlist.remove(section)



        self.entries.append((name, args))



        self.config.log.debug("Output: %s:%s = %s", dtype, name, pformat(args))
@@ -476,7 +502,7 @@ class KernelDoc: 
        # to ignore "[blah" in a parameter string.



        self.entry.parameterlist.append(param)

        org_arg = Re(r'\s\s+').sub(' ', org_arg, count=1)

        org_arg = Re(r'\s\s+').sub(' ', org_arg)

        self.entry.parametertypes[param] = org_arg



    def save_struct_actual(self, actual):
@@ -1384,7 +1410,6 @@ class KernelDoc: 
            return



        if doc_end.search(line):

            if self.entry.contents.strip("\n"):

            self.dump_section()



            # Look for doc_com + <text> + doc_end: