linux-toradex.git/scripts/kernel-doc, branch v4.11-rc1

kernel-doc: Handle returning pointers to pointers

2017-01-26T22:20:10+00:00

Clearly nobody ever tried to build the documentation for the radix tree
before:

include/linux/radix-tree.h:400: warning: cannot understand function
prototype: 'void ** radix_tree_iter_init(struct radix_tree_iter *iter,
unsigned long start) '

Indeed, the regexes only handled a single '*', not one-or-more.  I have
tried to fix that, but now I have perl regexes all over my hands, and
I fear I shall never be clean again.

Signed-off-by: Matthew Wilcox 
Signed-off-by: Jonathan Corbet

kernel-doc: properly document array arguments of function

2017-01-13T17:53:24+00:00

Documentation for array parameters passed in a function, like the first
argument in the function below, weren't getting exported in the rst
format, although they work fine for html and pdf formats:

  void drm_clflush_pages(struct page * pages[], unsigned long num_pages)

That's because the string key to store the description in the
parameterdescs dictionary doesn't have the [] suffix.  This cleans up
the suffix from the key before accessing the dictionary.

Signed-off-by: Gabriel Krisman Bertazi 
Fixes: c0d1b6ee780a ("kernel-doc: produce RestructuredText output")
Reviewed-by: Jani Nikula 
Signed-off-by: Jonathan Corbet

kernel-doc: make highlights more homogenous for the various backends

2017-01-04T22:08:14+00:00

$type_struct_full and friends are only used by the restructuredText
backend, because it needs to separate enum/struct/typedef/union from
the name of the type.  However, $type_struct is *also* used by the rST
backend.  This is confusing.

This patch replaces $type_struct's use in the rST backend with a new
$type_fallback; it modifies $type_struct so that it can be used in the
rST backend; and creates regular expressions like $type_struct
for enum/typedef/union, for use in all backends.

Note that, compared to $type_*_full, in the new regexes $1 includes both
the "kind" and the name (before, $1 was pretty much a constant).

Signed-off-by: Paolo Bonzini 
Acked-by: Jani Nikula 
Signed-off-by: Jonathan Corbet

kernel-doc: make member highlighting available in all backends

2017-01-04T22:08:03+00:00

Note that, in order to produce the correct Docbook markup, the "." or "->"
must be separated from the member name in the regex's captured fields.  For
consistency, this change is applied to $type_member and $type_member_func
too, not just to $type_member_xml.

List mode only prints the struct name, to avoid any undesired change in
the operation of docproc.

Signed-off-by: Paolo Bonzini 
Acked-by: Jani Nikula 
Signed-off-by: Jonathan Corbet

kernel-doc: include parameter type in docbook output

2017-01-04T22:07:53+00:00

The restructuredText output includes both the parameter type and
the name for functions and function-typed members.  Do the same
for docbook.

Signed-off-by: Paolo Bonzini 
Acked-by: Jani Nikula 
Signed-off-by: Jonathan Corbet

kernel-doc: strip attributes even if they have an argument

2017-01-04T22:07:42+00:00

An inline function can have an attribute, as in include/linux/log2.h,
and kernel-doc handles this already for simple cases.  However,
some attributes have arguments (e.g. the "target" attribute).
Handle those too.

Furthermore, attributes could be at the beginning of a function
declaration, before the return type.  To correctly handle this case,
you need to strip spaces after the attributes; otherwise, dump_function
is left confused.

Signed-off-by: Paolo Bonzini 
Acked-by: Jani Nikula 
Signed-off-by: Jonathan Corbet

kernel-doc: cleanup parameter type in function-typed arguments

2017-01-04T22:07:23+00:00

A prototype like

    /**
     * foo - sample definition
     * @bar: a parameter
     */
    int foo(int (*bar)(int x,
                       int y));

is currently producing

    .. c:function:: int foo (int (*bar) (int x,                    int y)

       sample definition

    **Parameters**

    ``int (*)(int x,                    int y) bar``
      a parameter

Collapse the spaces so that the output is nicer.

Signed-off-by: Paolo Bonzini 
Acked-by: Jani Nikula 
Signed-off-by: Jonathan Corbet

kernel-doc: add support for one line inline struct member doc comments

2016-11-16T23:30:27+00:00

kernel-doc supports documenting struct members "inline" since
a4c6ebede2f9 ("scripts/kernel-doc Allow struct arguments documentation
in struct body"). This requires the inline kernel-doc comments to have
the opening and closing comment markers (/** and */ respectively) on
lines of their own, even for short comments. For example:

	/**
	 * struct foo - struct documentation
	 */
	struct foo {
		/**
		 * @bar: member documentation
		 */
		int bar;
	};

Add support for one line inline comments:

	/**
	 * struct foo - struct documentation
	 */
	struct foo {
		/** @bar: member documentation */
		int bar;
	};

Note that mixing of the two in one doc comment is not allowed; either
both comment markers must be on lines of their own, or both must be on
the one line. This limitation keeps both the comments more uniform, and
kernel-doc less complicated.

Cc: Daniel Vetter 
Signed-off-by: Jani Nikula 
Signed-off-by: Jonathan Corbet

kernel-doc: better parsing of named variable arguments

2016-10-28T16:54:16+00:00

Without this patch we get warnings for named variable arguments.

    warning: No description found for parameter '...'
    warning: Excess function parameter 'args' description in 'alloc_ordered_workqueue'

Signed-off-by: Silvio Fricke 
Reviewed-by: Jani Nikula

docs: Special-case function-pointer parameters in kernel-doc

2016-09-06T14:02:49+00:00

Add yet another regex to kernel-doc to trap @param() references separately
and not produce corrupt RST markup.

Signed-off-by: Jonathan Corbet