Skip to contentSkip to conversation

kernel-doc: rename the kernel-doc directive 'functions' to 'identifiers'

PATCH In review Changbin Du 2 participants 2 messages Oct 31, 2019 – Nov 7, 2019

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH v3 1/1 kernel-doc: rename the kernel-doc directive 'functions' to 'identifiers'

The 'functions' directive is not only for functions, but also works for structs/unions. So the name is misleading. This patch renames it to 'identifiers', which specific the functions/types to be included in documentation. We keep the old name as an alias of the new one before all documentation are updated.

---
v2:
o use 'identifiers' as the new directive name.

---
 Documentation/doc-guide/kernel-doc.rst | 29 ++++++++++++++------------
 Documentation/sphinx/kerneldoc.py      | 17 +++++++++------
 2 files changed, 27 insertions(+), 19 deletions(-)
Documentation/doc-guide/kernel-doc.rst +16 -13
index 192c36af39e2..fff6604631ea 100644
@@ -476,6 +476,22 @@ internal: *[source-pattern ...]*
     .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
        :internal:
 
+identifiers: *[ function/type ...]*
+  Include documentation for each *function* and *type* in *source*.
+  If no *function* is specified, the documentation for all functions
+  and types in the *source* will be included.
+
+  Examples::
+
+    .. kernel-doc:: lib/bitmap.c
+       :identifiers: bitmap_parselist bitmap_parselist_user
+
+    .. kernel-doc:: lib/idr.c
+       :identifiers:
+
+functions: *[ function/type ...]*
+  This is an alias of the 'identifiers' directive and deprecated.
+
 doc: *title*
   Include documentation for the ``DOC:`` paragraph identified by *title* in
   *source*. Spaces are allowed in *title*; do not quote the *title*. The *title*
@@ -488,19 +504,6 @@ doc: *title*
     .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
        :doc: High Definition Audio over HDMI and Display Port
 
-functions: *[ function ...]*
-  Include documentation for each *function* in *source*.
-  If no *function* is specified, the documentation for all functions
-  and types in the *source* will be included.
-
-  Examples::
-
-    .. kernel-doc:: lib/bitmap.c
-       :functions: bitmap_parselist bitmap_parselist_user
-
-    .. kernel-doc:: lib/idr.c
-       :functions:
-
 Without options, the kernel-doc directive includes all documentation comments
 from the source file.
 
Documentation/sphinx/kerneldoc.py +11 -6
index 1159405cb920..4bcbd6ae01cd 100644
@@ -59,9 +59,10 @@ class KernelDocDirective(Directive):
     optional_arguments = 4
     option_spec = {
         'doc': directives.unchanged_required,
-        'functions': directives.unchanged,
         'export': directives.unchanged,
         'internal': directives.unchanged,
+        'identifiers': directives.unchanged,
+        'functions': directives.unchanged,
     }
     has_content = False
 
@@ -77,6 +78,10 @@ class KernelDocDirective(Directive):
 
         tab_width = self.options.get('tab-width', self.state.document.settings.tab_width)
 
+        # 'function' is an alias of 'identifiers'
+        if 'functions' in self.options:
+            self.options['identifiers'] = self.options.get('functions')
+
         # FIXME: make this nicer and more robust against errors
         if 'export' in self.options:
             cmd += ['-export']
@@ -86,11 +91,11 @@ class KernelDocDirective(Directive):
             export_file_patterns = str(self.options.get('internal')).split()
         elif 'doc' in self.options:
             cmd += ['-function', str(self.options.get('doc'))]
-        elif 'functions' in self.options:
-            functions = self.options.get('functions').split()
-            if functions:
-                for f in functions:
-                    cmd += ['-function', f]
+        elif 'identifiers' in self.options:
+            identifiers = self.options.get('identifiers').split()
+            if identifiers:
+                for i in identifiers:
+                    cmd += ['-function', i]
             else:
                 cmd += ['-no-doc-sections']
 
Signature · 1 line
2.20.1
maintainer
#1 lore raw
Quoted 11 lines · On Thu, 31 Oct 2019 21:52:45 +0800 Changbin Du <[email protected]> wrote:

The 'functions' directive is not only for functions, but also works for structs/unions. So the name is misleading. This patch renames it to 'identifiers', which specific the functions/types to be included in documentation. We keep the old name as an alias of the new one before all documentation are updated.

---
v2:
o use 'identifiers' as the new directive name.

It would have been nice to update that last text for v3 ... but the patch looks better, so I've gone ahead and applied it, thanks.

jon