Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit f2e86036 authored by Mike Rapoport's avatar Mike Rapoport Committed by Jonathan Corbet
Browse files

Documentation/sphinx: allow "functions" with no parameters 

When kernel-doc:: specified in .rst document without explicit directives,
it outputs both comment and DOC: sections. If a DOC: section was explicitly
included in the same document it will be duplicated. For example, the
output generated for Documentation/core-api/idr.rst [1] has "IDA
description" in the "IDA usage" section and in the middle of the API
reference.

This patch enables using "functions" directive without parameters to output
all the documentation excluding DOC: sections.

[1] https://www.kernel.org/doc/html/v4.17/core-api/idr.html



Signed-off-by: default avatarMike Rapoport <rppt@linux.vnet.ibm.com>
Acked-by: default avatarMatthew Wilcox <willy@infradead.org>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent dad05139

Documentation/doc-guide/kernel-doc.rst

+7 −2
Original line number Diff line number Diff line
@@ -488,14 +488,19 @@ doc: *title* 
    .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c

       :doc: High Definition Audio over HDMI and Display Port



functions: *function* *[...]*

functions: *[ function ...]*

  Include documentation for each *function* in *source*.

  If no *function* if specified, the documentaion for all functions

  and types in the *source* will be included.



  Example::

  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

+7 −3
Original line number Diff line number Diff line
@@ -47,7 +47,7 @@ class KernelDocDirective(Directive): 
    optional_arguments = 4

    option_spec = {

        'doc': directives.unchanged_required,

        'functions': directives.unchanged_required,

        'functions': directives.unchanged,

        'export': directives.unchanged,

        'internal': directives.unchanged,

    }
@@ -75,8 +75,12 @@ class KernelDocDirective(Directive): 
        elif 'doc' in self.options:

            cmd += ['-function', str(self.options.get('doc'))]

        elif 'functions' in self.options:

            for f in str(self.options.get('functions')).split():

            functions = self.options.get('functions').split()

            if functions:

                for f in functions:

                    cmd += ['-function', f]

            else:

                cmd += ['-no-doc-sections']



        for pattern in export_file_patterns:

            for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern):