On Fri, 03 Feb 2017, Matthew Wilcox <willy@xxxxxxxxxxxxx> wrote:
> I've written this patch, and it seems to work, but I don't really know
> what I'm doing and I fear I may have broken something. I don't know what:
>
> required_argument = 1
> optional_arguments = 4
>
> mean, so I don't know whether I should have adjusted them when adding
> this new option.
Apparently neither did I when I added them. I think optional_arguments
should be 0 for the kernel-doc directive.
> From 26896bd43618e30cb3563114663ad6c39cef7dc6 Mon Sep 17 00:00:00 2001
> From: Matthew Wilcox <mawilcox@xxxxxxxxxxxxx>
> Date: Thu, 26 Jan 2017 11:43:24 -0500
> Subject: [PATCH] kerneldoc: Add :nodoc: option
>
> This is functionality the perl script already has, we just need to
> expose it to our rst files.
> ---
> Documentation/sphinx/kerneldoc.py | 3 +++
> 1 file changed, 3 insertions(+)
>
> diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
> index d15e07f36881..d86d88da1d75 100644
> --- a/Documentation/sphinx/kerneldoc.py
> +++ b/Documentation/sphinx/kerneldoc.py
> @@ -47,6 +47,7 @@ class KernelDocDirective(Directive):
> optional_arguments = 4
> option_spec = {
> 'doc': directives.unchanged_required,
> + 'nodoc': directives.unchanged,
The commit message lacks the all important answer to *why* this is
needed. What's the use case? (I can guess, but I'd like it to be spelled
out, please.)
Generally I'd prefer hiding kernel-doc the script interface from
kernel-doc the directive. I think I already made a mistake by leaking
the script -function argument to the directive; perhaps e.g. "symbols"
would have been better than "functions", because you can use the
"functions" directive option to choose e.g. structs too. With that, I
think I would have preferred having "symbols" *without* specific symbols
listed equal your "nodoc". Perhaps overloading "functions" for this is
too confusing?
We could easily add e.g. "symbols" as a synonym for "functions", and
still make this so, but is it worth it?
BR,
Jani.
> 'functions': directives.unchanged_required,
> 'export': directives.unchanged,
> 'internal': directives.unchanged,
> @@ -74,6 +75,8 @@ 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 'nodoc' in self.options:
> + cmd += ['-no-doc-sections']
> elif 'functions' in self.options:
> for f in str(self.options.get('functions')).split():
> cmd += ['-function', f]
--
Jani Nikula, Intel Open Source Technology Center
--
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
