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

$type_struct_full and friends are only used by the restructuredText
backend, because it needs to separate enum/struct/typedef/uni

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

$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 <[email protected]>
Acked-by: Jani Nikula <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

kernel-doc: make member highlighting available in all backends

Note that, in order to produce the correct Docbook markup, the "." or "->"
must be separated from the member name in the regex's captur

kernel-doc: make member highlighting available in all backends

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 <[email protected]>
Acked-by: Jani Nikula <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

kernel-doc: include parameter type in docbook output

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

Si

kernel-doc: include parameter type in docbook output

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 <[email protected]>
Acked-by: Jani Nikula <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

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

An inline function can have an attribute, as in include/linux/log2.h,
and kernel-doc handles this already for simple cases. However,
some

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

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 <[email protected]>
Acked-by: Jani Nikula <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

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

A prototype like

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

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

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 <[email protected]>
Acked-by: Jani Nikula <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

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

kernel-doc supports documenting struct members "inline" since
a4c6ebede2f9 ("scripts/kernel-doc Allow struct arguments document

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

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 <[email protected]>
Signed-off-by: Jani Nikula <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

kernel-doc: better parsing of named variable arguments

Without this patch we get warnings for named variable arguments.

warning: No description found for parameter '...'
warning: Excess fun

kernel-doc: better parsing of named variable arguments

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 <[email protected]>
Reviewed-by: Jani Nikula <[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

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

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

Signed-off-by: Jonathan C

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

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

Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: make kernel-doc handle varargs properly

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.

docs: make kernel-doc handle varargs properly

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 <[email protected]>

show more ...

docs-rst: kernel-doc: fix typedef output in RST format

When using a typedef function like this one:
typedef bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);

The Sp

docs-rst: kernel-doc: fix typedef output in RST format

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 <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs-rst: improve typedef parser

Improve the parser to handle typedefs like:

typedef bool v4l2_check_dv_timings_fnc(const struct v4l2_dv_timings *t, void *handle);

Signed-off-by: Mauro Carvalho C

docs-rst: improve typedef parser

Improve the parser to handle typedefs like:

typedef bool v4l2_check_dv_timings_fnc(const struct v4l2_dv_timings *t, void *handle);

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs-rst: kernel-doc: better output struct members

Right now, for a struct, kernel-doc produces the following output:

.. c:type:: struct v4l2_prio_state

stores the priority states

**Definit

docs-rst: kernel-doc: better output struct members

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 <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

doc-rst: Revert "kernel-doc: fix handling of address_space tags"

This reverts commit a88b1672d4ddf9895eb53e6980926d5e960dea8e.

From the origin comit log::

The RST cpp:function handler is very pe

doc-rst: Revert "kernel-doc: fix handling of address_space tags"

This reverts commit a88b1672d4ddf9895eb53e6980926d5e960dea8e.

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 <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

doc-rst: kernel-doc: fix a change introduced by mistake

changeset b7e67f6c1bf7 ("doc-rst: linux_tv: supress lots of warnings")
were meant to touch only on media files, but it also touched
at this sc

doc-rst: kernel-doc: fix a change introduced by mistake

changeset b7e67f6c1bf7 ("doc-rst: linux_tv: supress lots of warnings")
were meant to touch only on media files, but it also touched
at this script by mistake. Revert such change.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>

show more ...

doc-rst: kernel-doc: fix handling of address_space tags

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: WARN

doc-rst: kernel-doc: fix handling of address_space tags

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 <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

kernel-doc: Fix up warning output

While trying to make gpu docs warning free I stumbled over one output
which wasn't following proper compiler error output standards. Fix it
up for more quickfix awe

kernel-doc: Fix up warning output

While trying to make gpu docs warning free I stumbled over one output
which wasn't following proper compiler error output standards. Fix it
up for more quickfix awesomeness.

Cc: Jonathan Corbet <[email protected]>
Cc: Jani Nikula <[email protected]>
Cc: [email protected]
Signed-off-by: Daniel Vetter <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

doc-rst: linux_tv: remove trailing comments

The conversion script added some comments at the end.
They point to the original DocBook files, with will be
removed after the manual fixes. So, they'll b

doc-rst: linux_tv: remove trailing comments

The conversion script added some comments at the end.
They point to the original DocBook files, with will be
removed after the manual fixes. So, they'll be pointing
to nowere. So, remove those comments.

They'll be forever stored at the Kernel tree. So, if
someone wants the references, it is just a matter of
looking at the backlog.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>

show more ...

doc-rst: linux_tv: supress lots of warnings

The c language parser checks if there are duplicated object
definitions. That causes lots of warnings like:
WARNING: duplicate C object description of io

doc-rst: linux_tv: supress lots of warnings

The c language parser checks if there are duplicated object
definitions. That causes lots of warnings like:
WARNING: duplicate C object description of ioctl

Let's remove those by telling Sphinx that the language for
those objects are c++. The look of the descriptions will
be close, and the warnings will be gone.

Please notice that we had to keep a few of them as C, as
the c++ parser seems to be broken when it finds an enum.

Yet, this reduced from 219 warnings to 143, with is
a good thing.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>

show more ...

kernel-doc: unify all EXPORT_SYMBOL scanning to one place

Scan all input files for EXPORT_SYMBOLs along with the explicitly
specified export files before actually parsing anything.

Signed-off-by: J

kernel-doc: unify all EXPORT_SYMBOL scanning to one place

Scan all input files for EXPORT_SYMBOLs along with the explicitly
specified export files before actually parsing anything.

Signed-off-by: Jani Nikula <[email protected]>

show more ...

kernel-doc: add support for specifying extra files for EXPORT_SYMBOLs

If the kernel-doc comments for functions are not in the same file as the
EXPORT_SYMBOL statements, the -export and -internal out

kernel-doc: add support for specifying extra files for EXPORT_SYMBOLs

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 <[email protected]>

show more ...

kernel-doc: abstract filename mapping

Reduce duplication in follow-up work. No functional changes.

Signed-off-by: Jani Nikula <[email protected]>

kernel-doc: add missing semi-colons in option parsing

Signed-off-by: Jani Nikula <[email protected]>

kernel-doc: do not warn about duplicate default section names

Since

commit 32217761ee9db0215350dfe1ca4e66f312fb8c54
Author: Jani Nikula <[email protected]>
Date: Sun May 29 09:40:44 2016 +030

kernel-doc: do not warn about duplicate default section names

Since

commit 32217761ee9db0215350dfe1ca4e66f312fb8c54
Author: Jani Nikula <[email protected]>
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 <[email protected]>

show more ...

kernel-doc: remove old debug cruft from dump_section()

No functional changes.

Signed-off-by: Jani Nikula <[email protected]>

docs: kernel-doc: Add "example" and "note" to the magic section types

Lots of kerneldoc entries use "example:" or "note:" as section headers.
Until such a time as we can make them use proper markup,

docs: kernel-doc: Add "example" and "note" to the magic section types

Lots of kerneldoc entries use "example:" or "note:" as section headers.
Until such a time as we can make them use proper markup, make them work as
intended.

Signed-off-by: Jonathan Corbet <[email protected]>

show more ...