Commit 36bc683d authored by Changbin Du's avatar Changbin Du Committed by Jonathan Corbet
Browse files

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.

Signed-off-by: default avatarChangbin Du <changbin.du@gmail.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent e80d8938

Documentation/doc-guide/kernel-doc.rst

+16 −13
Original line number Diff line number Diff line
@@ -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
Original line number Diff line number Diff line
@@ -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']

CRA Git | Maintained and supported by SUSTech CRA and CCSE