lib/crc32c defines one parameter as:
const u32 (*tab)[256]
Better handle parenthesis, to avoid those warnings:
./lib/crc32.c:149: warning: No description found for parameter 'tab)[256]'
./lib/crc32.c:149: warning: Excess function parameter 'tab' description in 'crc32_le_generic'
./lib/crc32.c:294: warning: No description found for parameter 'tab)[256]'
./lib/crc32.c:294: warning: Excess function parameter 'tab' description in 'crc32_be_generic'
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
On ReST, adding a text like ``literal`` is valid. However,
the kernel-doc script won't handle it fine.
We really need this feature, in order to escape things like
%ph, with is found on some C files.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <mawilcox@microsoft.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <krisman@collabora.co.uk>
Fixes: c0d1b6ee78 ("kernel-doc: produce RestructuredText output")
Reviewed-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
$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 <pbonzini@redhat.com>
Acked-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <pbonzini@redhat.com>
Acked-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <pbonzini@redhat.com>
Acked-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <pbonzini@redhat.com>
Acked-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <pbonzini@redhat.com>
Acked-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
kernel-doc supports documenting struct members "inline" since
a4c6ebede2 ("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 <daniel@ffwll.ch>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <silvio.fricke@gmail.com>
Reviewed-by: Jani Nikula <jani.nikula@intel.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Add yet another regex to kernel-doc to trap @param() references separately
and not produce corrupt RST markup.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
As far as I can tell, the handling of "..." arguments has never worked
right, so any documentation provided was ignored in favor of "variable
arguments." This makes kernel-doc handle "@...:" as documented. It does
*not* fix spots in kerneldoc comments that don't follow that convention,
but they are no more broken than before.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
When using a typedef function like this one:
typedef bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);
The Sphinx C domain expects it to create a c:type: reference,
as that's the way it creates the type references when parsing
a c:function:: declaration.
So, a declaration like:
.. c:function:: bool v4l2_valid_dv_timings (const struct v4l2_dv_timings * t, const struct v4l2_dv_timings_cap * cap, v4l2_check_dv_timings_fnc fnc, void * fnc_handle)
Will create a cross reference for :c:type:`v4l2_check_dv_timings_fnc`.
So, when outputting such typedefs in RST format, we need to handle
this special case, as otherwise it will produce those warnings:
./include/media/v4l2-dv-timings.h:43: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
./include/media/v4l2-dv-timings.h:60: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
./include/media/v4l2-dv-timings.h:81: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
So, change the kernel-doc script to produce a RST output for the
above typedef as:
.. c:type:: v4l2_check_dv_timings_fnc
**Typedef**: timings check callback
**Syntax**
``bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);``
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Right now, for a struct, kernel-doc produces the following output:
.. c:type:: struct v4l2_prio_state
stores the priority states
**Definition**
::
struct v4l2_prio_state {
atomic_t prios[4];
};
**Members**
``atomic_t prios[4]``
array with elements to store the array priorities
Putting a member name in verbatim and adding a continuation line
causes the LaTeX output to generate something like:
item[atomic_t prios\[4\]] array with elements to store the array priorities
Everything inside "item" is non-breakable, with may produce
lines bigger than the column width.
Also, for function members, like:
int (* rx_read) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num);
It puts the name of the member at the end, like:
int (*) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num) read
With is very confusing.
The best is to highlight what really matters: the member name.
is a secondary information.
So, change kernel-doc, for it to produce the output on a different way:
**Members**
``prios[4]``
array with elements to store the array priorities
Also, as the type is not part of LaTeX "item[]", LaTeX will split it into
multiple lines, if needed.
So, both LaTeX/PDF and HTML outputs will look good.
It should be noticed, however, that the way Sphinx LaTeX output handles
things like:
Foo
bar
is different than the HTML output. On HTML, it will produce something
like:
**Foo**
bar
While, on LaTeX, it puts both foo and bar at the same line, like:
**Foo** bar
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This reverts commit a88b1672d4.
From the origin comit log::
The RST cpp:function handler is very pedantic: it doesn't allow any
macros like __user on it
Since the kernel-doc parser does NOT make use of the cpp:domain, there
is no need to change the kernel-doc parser eleminating the address_space
tags.
Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The RST cpp:function handler is very pedantic: it doesn't allow any
macros like __user on it:
Documentation/media/kapi/dtv-core.rst:28: WARNING: Error when parsing function declaration.
If the function has no return type:
Error in declarator or parameters and qualifiers
Invalid definition: Expecting "(" in parameters_and_qualifiers. [error at 8]
ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
--------^
If the function has a return type:
Error in declarator or parameters and qualifiers
If pointer to member declarator:
Invalid definition: Expected '::' in pointer to member (function). [error at 37]
ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
-------------------------------------^
If declarator-id:
Invalid definition: Expecting "," or ")" in parameters_and_qualifiers, got "*". [error at 102]
ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
------------------------------------------------------------------------------------------------------^
So, we have to remove it from the function prototype.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Scan all input files for EXPORT_SYMBOLs along with the explicitly
specified export files before actually parsing anything.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
If the kernel-doc comments for functions are not in the same file as the
EXPORT_SYMBOL statements, the -export and -internal output selections do
not work as expected. This is typically the case when the kernel-doc
comments are in header files next to the function declarations and the
EXPORT_SYMBOL statements are next to the function definitions in the
source files.
Let the user specify additional source files in which to look for the
EXPORT_SYMBOLs using the new -export-file FILE option, which may be
given multiple times.
The pathological example for this is include/net/mac80211.h, which has
all the kernel-doc documentation for the exported functions defined in a
plethora of source files net/mac80211/*.c.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Since
commit 32217761ee
Author: Jani Nikula <jani.nikula@intel.com>
Date: Sun May 29 09:40:44 2016 +0300
kernel-doc: concatenate contents of colliding sections
we started getting (more) errors on duplicate section names, especially
on the default section name "Description":
include/net/mac80211.h:3174: warning: duplicate section name 'Description'
This is usually caused by a slightly unorthodox placement of parameter
descriptions, like in the above case, and kernel-doc resetting back to
the default section more than once within a kernel-doc comment.
Ignore warnings on the duplicate section name automatically assigned by
kernel-doc, and only consider explicitly user assigned duplicate section
names an issue.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
