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: Mike Rapoport <rppt@xxxxxxxxxxxxxxxxxx> Acked-by: Matthew Wilcox <willy@xxxxxxxxxxxxx> --- Documentation/doc-guide/kernel-doc.rst | 9 +++++++-- Documentation/sphinx/kerneldoc.py | 10 +++++++--- 2 files changed, 14 insertions(+), 5 deletions(-) diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index 80383b1..8db53cd 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -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. diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py index fbedcc3..9d0a7f0 100644 --- a/Documentation/sphinx/kerneldoc.py +++ b/Documentation/sphinx/kerneldoc.py @@ -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(): - cmd += ['-function', f] + 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): -- 2.7.4 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
