Re: [PATCH v3 1/2] Documentation/sphinx: allow "functions" with no parameters
On Sat, 30 Jun 2018 17:59:27 +0300 Mike Rapoport wrote: > > > > Is this the right syntax? Should we rather have: > > > > .. kernel-doc:: lib/idr.c > >:functions: * > > IMHO :functions: with no parameters is simpler. What I would really like to have there, actually, is a regex match (or, probably better, a shell-glob match). It would be easy to add, I've just never gotten around to it. That would make the above syntax just work for those who preferred it. jon -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v3 1/2] Documentation/sphinx: allow "functions" with no parameters
On Sat, Jun 30, 2018 at 04:21:56AM -0700, Matthew Wilcox wrote: > On Sat, Jun 30, 2018 at 12:05:10AM +0300, Mike Rapoport wrote: > > @@ -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 > > "is specified". "documentation". > > > - Example:: > > + Examples:: > > > > .. kernel-doc:: lib/bitmap.c > > :functions: bitmap_parselist bitmap_parselist_user > > > > +.. kernel-doc:: lib/idr.c > > + :functions: > > Is this the right syntax? Should we rather have: > > .. kernel-doc:: lib/idr.c >:functions: * IMHO :functions: with no parameters is simpler. -- Sincerely yours, Mike. -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v3 1/2] Documentation/sphinx: allow "functions" with no parameters
On Sat, Jun 30, 2018 at 12:05:10AM +0300, Mike Rapoport wrote: > @@ -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 "is specified". "documentation". > - Example:: > + Examples:: > > .. kernel-doc:: lib/bitmap.c > :functions: bitmap_parselist bitmap_parselist_user > > +.. kernel-doc:: lib/idr.c > + :functions: Is this the right syntax? Should we rather have: .. kernel-doc:: lib/idr.c :functions: * -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v3 1/2] 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: Mike Rapoport
Acked-by: Matthew Wilcox
---
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 majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
