Skip to contentSkip to conversation

Better handle xform class

PATCH Applied Mauro Carvalho Chehab 2 participants 4 messages Mar 6 – Mar 9 Documentation

lore
Share & tools
lore

Mauro Carvalho Chehab

author
#0 lore raw

v2 cover Better handle xform class

Hi Jon,

Those two patches are meant to help re-using kernel-doc outside Linux Kernel. Currently, QEMU uses it, but it requires a different transforms table. The first patch adds support to overriding it there; The second one documents its ABI.

-

I'm picking those two patches from the past series. Those were merged together with man fixes, but they're unrelated.

So, let's place them in separate.

Mauro Carvalho Chehab (2):
docs: kdoc_files: allows the caller to use a different xforms class
docs: kdoc_files: document KernelFiles() ABI

 tools/lib/python/kdoc/kdoc_files.py | 53 +++++++++++++++++++++++++++--
 1 file changed, 50 insertions(+), 3 deletions(-)
Signature · 1 line
2.52.0
author
#1 lore raw

PATCH v2 1/2 docs: kdoc_files: allows the caller to use a different xforms class

While the main goal for kernel-doc is to be used inside the Linux Kernel, other open source projects could benefit for it. That's currently the case of QEMU, which has a fork, mainly due to two reasons:

- they need an extra C function transform rule;
- they handle the html output a little bit different.

Add an extra optional argument to make easier for the code to be shared, as, with that, QEMU can just create a new derivated class that will contain its specific rulesets, and just copy the remaining kernel-doc files as-is.

Signed-off-by Mauro Carvalho Chehab <[email protected]>
---
 tools/lib/python/kdoc/kdoc_files.py | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)
tools/lib/python/kdoc/kdoc_files.py +7 -2
index 33618c6abec2..c35e033cf123 100644
@@ -118,7 +118,7 @@ class KernelFiles():
         if fname in self.files:
             return
 
-        doc = KernelDoc(self.config, fname, CTransforms())
+        doc = KernelDoc(self.config, fname, self.xforms)
         export_table, entries = doc.parse_kdoc()
 
         self.export_table[fname] = export_table

@@ -154,7 +154,7 @@ class KernelFiles():
 
         self.error(f"Cannot find file {fname}")
 
-    def __init__(self, verbose=False, out_style=None,
+    def __init__(self, verbose=False, out_style=None, xforms=None,
                  werror=False, wreturn=False, wshort_desc=False,
                  wcontents_before_sections=False,
                  logger=None):

@@ -193,6 +193,11 @@ class KernelFiles():
         self.config.wshort_desc = wshort_desc
         self.config.wcontents_before_sections = wcontents_before_sections
 
+        if xforms:
+            self.xforms = xforms
+        else:
+            self.xforms = CTransforms()
+
         if not logger:
             self.config.log = logging.getLogger("kernel-doc")
         else:
Signature · 1 line
2.52.0
author
#2 lore raw

PATCH v2 2/2 docs: kdoc_files: document KernelFiles() ABI

In reply to Mauro Carvalho Chehab

The KernelFiles is the main entry point to run kernel-doc, being used by both tools/docs/kernel-doc and Documentation/sphinx/kerneldoc.py.

It is also used on QEMU, which also uses the kernel-doc libraries from tools/lib/python/kdoc.

Properly describe its ABI contract.

Signed-off-by Mauro Carvalho Chehab <[email protected]>
---
 tools/lib/python/kdoc/kdoc_files.py | 44 ++++++++++++++++++++++++++++-
 1 file changed, 43 insertions(+), 1 deletion(-)
tools/lib/python/kdoc/kdoc_files.py +43 -1
index c35e033cf123..8c2059623949 100644
@@ -91,7 +91,49 @@ class KernelFiles():
     """
     Parse kernel-doc tags on multiple kernel source files.
 
-    There are two type of parsers defined here:
+    This is the main entry point to run kernel-doc. This class is initialized
+    using a series of optional arguments:
+
+    ``verbose``
+        If True, enables kernel-doc verbosity. Default: False.
+
+    ``out_style``
+        Class to be used to format output. If None (default),
+        only report errors.
+
+    ``xforms``
+        Transforms to be applied to C prototypes and data structs.
+        If not specified, defaults to xforms = CFunction()
+
+    ``werror``
+        If True, treat warnings as errors, retuning an error code on warnings.
+
+        Default: False.
+
+    ``wreturn``
+        If True, warns about the lack of a return markup on functions.
+
+        Default: False.
+    ``wshort_desc``
+        If True, warns if initial short description is missing.
+
+        Default: False.
+
+    ``wcontents_before_sections``
+        If True, warn if there are contents before sections (deprecated).
+        This option is kept just for backward-compatibility, but it does
+        nothing, neither here nor at the original Perl script.
+
+        Default: False.
+
+    ``logger``
+        Optional logger class instance.
+
+        If not specified, defaults to use: ``logging.getLogger("kernel-doc")``
+
+    Note:
+        There are two type of parsers defined here:
+
         - self.parse_file(): parses both kernel-doc markups and
           ``EXPORT_SYMBOL*`` macros;
         - self.process_export_file(): parses only ``EXPORT_SYMBOL*`` macros.
Signature · 1 line
2.52.0
maintainer Applied
#3 lore raw
In reply to Mauro Carvalho Chehab
Quoted 12 lines · Mauro Carvalho Chehab

Hi Jon,

Those two patches are meant to help re-using kernel-doc outside Linux Kernel. Currently, QEMU uses it, but it requires a different transforms table. The first patch adds support to overriding it there; The second one documents its ABI.

-

I'm picking those two patches from the past series. Those were merged together with man fixes, but they're unrelated.

Quoted 8 lines

So, let's place them in separate.

Mauro Carvalho Chehab (2):
docs: kdoc_files: allows the caller to use a different xforms class
docs: kdoc_files: document KernelFiles() ABI

 tools/lib/python/kdoc/kdoc_files.py | 53 +++++++++++++++++++++++++++--
 1 file changed, 50 insertions(+), 3 deletions(-)

Applied, thanks.

jon