The existing message
"Excess struct/union/enum/typedef member [...]"
made it sound like this would already be done, but the
code is never invoked for enums or typedefs (and really
can't be).
Add some code to the enum dumper to handle this there
instead.
While at it, also make the above message more accurate
by simply dumping the type that was passed in, and pass
the struct/union differentiation in.
Signed-off-by: Johannes Berg <johannes.berg@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Reported by Johannes Berg [1]. Problem here: function
process_proto_type() concatenates the striped lines of declaration
without any whitespace. A one-liner of::
struct something {
struct foo
bar;
};
has to be::
struct something {struct foo bar;};
Without the patching process_proto_type(), the result missed the space
between 'foo' and 'bar'::
struct something {struct foobar;};
Bugfix of process_proto_type() brings next error when blank lines
between enum declaration::
warning: Enum value ' ' not described in enum 'foo'
Problem here: dump_enum() does not strip leading whitespaces from
the concatenated string (with the new additional space from
process_proto_type).
[1] https://www.mail-archive.com/linux-doc@vger.kernel.org/msg12410.html
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
- Use more portable shebang for Perl scripts
- Remove trailing spaces from GCC version in kernel log
- Make initramfs generation deterministic
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1
iQIcBAABAgAGBQJZXrq2AAoJED2LAQed4NsGzlIP/jmVGusmFIP2jFC7zUEVaKsp
VK4tezn0aa/c/BsY+kGu3OVqUHgspQSjNa4wH27A+z4/skkxPQKUmF1IY+8/W5yc
aR0Yn76vzjjNYNl6AS3fA+QP+dBn+UdQDA2jMNKyu/3fACjiVY9BBx2ZdhJMwJcy
WrAax/fQNnRjmAQFQpptNBvYZn1B7A/7iFCPpQbPP6GFsqSJ2zMtRGjtoaeFgpV3
On6d4uAcgAcnEHw1zomWTx0N0LghW+L6Te9PoHyPZnyxfi+OVN/bmakoy7qs1uUh
zWucIhpBc8bshx6s4VnJ5OZhFNVEkeSjq5CivYKnU0u4waKb7suxuI1+D6e7uRrA
2OuXmhm7sRvGHwGIxEdJAOlF0PNecYSgJPv+ZDcOxVMy72REUZUEjgThti/vLdUn
9iVDXn/ExOxqJW7isth1MTn3FBsDUIZDKK5EypgY/oAuECR6pQnjD3HjojJBACau
OqbsZDPqmDiY3sxzU1GcAbrhAJiGyWXV7hAKsROoVlgwU2fu0Al2HHtDzEjqLrzK
wIvAD+lsWKiFP1zXlCnrsgjXgn/RFG1cHLiqEhtPy+HpqNzXoXDRs5kcTsr5Z0fj
3DlMNqa7Bv0raL3+XG2pp9OR5gWdLxmOuPIR/TNU3JubTRur4SElJtXyDoHVTJti
s4mye73xjjcifGEwpZQw
=C+WJ
-----END PGP SIGNATURE-----
Merge tag 'kbuild-misc-v4.13' of git://git.kernel.org/pub/scm/linux/kernel/git/masahiroy/linux-kbuild
Pull misc Kbuild updates from Masahiro Yamada:
- Use more portable shebang for Perl scripts
- Remove trailing spaces from GCC version in kernel log
- Make initramfs generation deterministic
* tag 'kbuild-misc-v4.13' of git://git.kernel.org/pub/scm/linux/kernel/git/masahiroy/linux-kbuild:
kbuild: create deterministic initramfs directory listings
scripts/mkcompile_h: Remove trailing spaces from compiler version
scripts: Switch to more portable Perl shebang
DECLARE_HASHTABLE needs similar handling to DECLARE_BITMAP
because otherwise kernel-doc assumes the member name is the
second, not first macro parameter.
Signed-off-by: Jakub Kicinski <jakub.kicinski@netronome.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The default NetBSD package manager is pkgsrc and it installs Perl
along other third party programs under custom and configurable prefix.
The default prefix for binary prebuilt packages is /usr/pkg, and the
Perl executable lands in /usr/pkg/bin/perl.
This change switches "/usr/bin/perl" to "/usr/bin/env perl" as it's
the most portable solution that should work for almost everybody.
Perl's executable is detected automatically.
This change switches -w option passed to the executable with more
modern "use warnings;" approach. There is no functional change to the
default behavior.
While there, drop "require 5" from scripts/namespace.pl (Perl from 1994?).
Signed-off-by: Kamil Rytarowski <n54@gmx.com>
Signed-off-by: Masahiro Yamada <yamada.masahiro@socionext.com>
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>
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 <corbet@lwn.net>
Cc: Jani Nikula <jani.nikula@intel.com>
Cc: linux-doc@vger.kernel.org
Signed-off-by: Daniel Vetter <daniel.vetter@intel.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>
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 <corbet@lwn.net>
Opt-in since this wreaks the rst output and must be removed
by consumers again. This is useful to adjust the linenumbers
for included kernel-doc snippets in shinx. With that sphinx
error message will be accurate when there's issues with the
rst-ness of the kernel-doc comments.
Especially when transitioning a new docbook .tmpl to .rst this
is extremely useful, since you can just use your editors compilation
quickfix list to accurately jump from error to error.
v2:
- Also make sure that we filter the LINENO for purpose/at declaration
start so it only shows for selected blocks, not all of them (Jani).
While at it make it a notch more accurate.
- Avoid undefined $lineno issues. I tried filtering these out at the
callsite, but Jani spotted more when linting the entire kernel.
Unamed unions and similar things aren't stored consistently and end
up with an undefined line number (but also no kernel-doc text, just
the parameter type). Simplify things and filter undefined line
numbers in print_lineno() to catch them all.
v3: Fix LINENO 0 issue for kernel-doc comments without @param: lines
or any other special sections that directly jump to the description
after the "name - purpose" line. Only really possible for functions
without parameters. Noticed by Jani.
Cc: Jani Nikula <jani.nikula@intel.com>
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
state3 = prototype parsing, so name them accordingly.
Cc: Jani Nikula <jani.nikula@intel.com>
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Further up in the state machinery we switch from STATE_NAME to
STATE_DOCBLOCK when we match /$doc_block/. Which means this block of
code here is entirely unreachable, unless there are multiple DOC:
sections within a single kernel-doc comment.
Getting a list of all the files with more than one DOC: section using
$ git grep -c " * DOC:" | grep -v ":1$"
and then doing a full audit of them reveals there are no such comment
blocks in the kernel.
Supporting multiple DOC: sections in a single kernel-doc comment does
not seem like a recommended way of doing things anyway, so nuke the code
for simplicity.
Cc: Jani Nikula <jani.nikula@intel.com>
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
[Jani: amended the commit message]
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
If the documentation comment does not have params or sections, the
section heading may leak from the previous documentation comment.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
If there are multiple sections with the same section name, the current
implementation results in several sections by the same heading, with the
content duplicated from the last section to all. Even if there's the
error message, a more graceful approach is to combine all the
identically named sections into one, with concatenated contents.
With the supported sections already limited to select few, there are
massively fewer collisions than there used to be, but this is still
useful for e.g. when function parameters are documented in the middle of
a documentation comment, with description spread out above and
below. (This is not a recommended documentation style, but used in the
kernel nonetheless.)
We can now also demote the error to a warning.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
kernel-doc currently identifies anything matching "section header:"
(specifically a string of word characters and spaces followed by a
colon) as a new section in the documentation comment, and renders the
section header accordingly.
Unfortunately, this turns all uses of colon into sections, mostly
unintentionally. Considering the output, erroneously creating sections
when not intended is always worse than erroneously not creating sections
when intended. For example, a line with "http://example.com" turns into
a "http" heading followed by "//example.com" in normal text style, which
is quite ugly. OTOH, "WARNING: Beware of the Leopard" is just fine even
if "WARNING" does not turn into a heading.
It is virtually impossible to change all the kernel-doc comments, either
way. The compromise is to pick the most commonly used and depended on
section headers (with variants) and accept them as section headers.
The accepted section headers are, case insensitive:
* description:
* context:
* return:
* returns:
Additionally, case sensitive:
* @return:
All of the above are commonly used in the kernel-doc comments, and will
result in worse output if not identified as section headers. Also,
kernel-doc already has some special handling for all of them, so there's
nothing particularly controversial in adding more special treatment for
them.
While at it, improve the whitespace handling surrounding section
names. Do not consider the whitespace as part of the name.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
If a param description spans multiple lines, check any leading
whitespace in the first continuation line, and remove same amount of
whitespace from following lines.
This allows indentation in the multi-line parameter descriptions for
aesthetical reasons while not causing accidentally significant
indentation in the rst output.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Handle whitespace on the first line of param text as if it was the empty
string. There is no need to add the newline in this case. This improves
the rst output in particular, where blank lines may be problematic in
parameter lists.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Move away from field lists, and simply use **strong emphasis** for
section headings on lines of their own. Do not use rst section headings,
because their nesting depth depends on the surrounding context, which
kernel-doc has no knowledge of. Also, they do not need to end up in any
table of contexts or indexes.
There are two related immediate benefits. Field lists are typically
rendered in two columns, while the new style uses the horizontal width
better. With no extra indent on the left, there's no need to be as fussy
about it. Field lists are more susceptible to indentation problems than
the new style.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
The inline member markup allows whitespace lines before the actual
documentation starts. Strip the leading blank lines. This improves the
rst output.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
The use of these is confusing in the script, and per this grep, they're
not used anywhere anyway:
$ git grep " \* [%$&][a-zA-Z0-9_]*:" -- *.[ch] | grep -v "\$\(Id\|Revision\|Date\)"
While at it, throw out the constants array, nothing is ever put there
again.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Link "&foo->bar", "&foo->bar()", "&foo.bar", and "&foo.bar()" to the
struct/union/enum foo definition. The members themselves do not
currently have anchors to link to, but this is better than nothing, and
promotes a universal notation.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Let the user use "&union foo" and "&typedef foo" to reference foo. The
difference to using "union &foo", "typedef &foo", or just "&foo" (which
are valid too) is that "union" and "typedef" become part of the link
text.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
It's possible to use &foo to reference structs, enums, typedefs, etc. in
the Sphinx C domain. Thus do not prefix the links with "struct".
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
If the user requests a specific DOC: section by name, do not output its
section title. In these cases, the surrounding context already has a
heading, and the DOC: section title is only used as an identifier and a
heading for clarity in the source file.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Make the output selection a bit more readable by adding constants for
the various types of output selection. While at it, actually call the
variable for choosing what to output $output_selection.
No functional changes.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Make the state machine a bit more readable by adding constants for
parser states and inline member documentation parser substates. While at
it, rename the "split" documentation to "inline" documentation.
No functional changes.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Currently we use docproc to figure out which symbols are exported, and
then docproc calls kernel-doc on specific functions, to get
documentation on exported functions. According to git blame and docproc
comments, this is due to historical reasons, as functions and their
corresponding EXPORT_SYMBOL* may have been in different files. However
for more than ten years the recommendation in CodingStyle has been to
place the EXPORT_SYMBOL* immediately after the closing function brace
line.
Additionally, the kernel-doc comments for functions are generally placed
above the function definition in the .c files (i.e. where the
EXPORT_SYMBOL* is) rather than above the declaration in the .h
files. There are some exceptions to this, but AFAICT none of these are
included in DocBook documentation using the "!E" docproc directive.
Therefore, assuming the EXPORT_SYMBOL* and kernel-doc are with the
function definition, kernel-doc can extract the exported vs. not
information by making two passes on the input file. Add support for that
via the new -export and -internal parameters.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
I'm not quite sure why the errors below are happening, but this fixes
them.
Use of uninitialized value in string ne at ./scripts/kernel-doc line 1819, <IN> line 6494.
Use of uninitialized value $_[0] in join or string at ./scripts/kernel-doc line 1759, <IN> line 6494.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
First, the headings for structs, enums and typedefs will be similar to
functions. Second, this provides a kind of namespace for cross
references. Third, and most importantly, the return and parameter types
from .. c:function:: definitions will automagically become cross
references to the documented types.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
If given the -rst flag, output will now be in RestructuredText. Various
glitches to be worked out yet.
In the end I decided not to use RST section headings within the kerneldoc
comments. gpu.tmpl already has headings five levels deep; adding more is
not going to bring clarity.
This is really just Jani Nikula's asciidoc change with the serial numbers
filed off. It's a hack job that doubtless needs a lot of cleaning up.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Instead of having the kernel-doc usage in both comments and in output to
the user, merge them all to one here document. While at it, imrove the
text and make it pretty. Give shoemaker's children some shoes.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
fixes and various document tweaks.
One patch reaches out of the documentation subtree to fix a comment in
init/do_mounts_rd.c. There didn't seem to be anybody more appropriate to
take that one, so I accepted it.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1
iQIcBAABAgAGBQJWmmJ8AAoJEI3ONVYwIuV6uqwP/0mnqdxVWo47ohaYJP7q0Soh
ovJAbfttxKnkmOdGbWcNIJtTiw+MpdF805CYR+2treE0zvEEDodg7BhkDnmKZJ9n
F1r53JrIj769E1c5ETmWTHcBt3jjtKyQIbBmDr4YTgX91dlKF28o1bMmyDECWIcT
PktTlPUidDtffKMn3klh6baPCMrTpLJ8aLshBzUrQhrQY8lxcZKAU+98vtFzYofG
LXCSulMYXumb7XBxErTLQZhmJslD4gaDMh2xkov6ALS8XNHnfoUIFRbArAllNfTf
LQGJ6Q5qnn58UWi9F/vgDqx7+d1KIPUjBxJR9wfa0w9ggQhA9ly2BSN/fllbiSbp
yIi1JS4hwBe8H/h577BNC3xjmgVN7mazZsXlS+fg3G16gpv4JdWeRY4efjosFIzQ
EIJxB8qAovUNqw4s1mzRIJ5B9L7PEK27O6z8N27Fiw4EigtMTFAOC2/GD3ELx4iJ
p1doiSr+wjfDcFd8kdIUiDKGrTSTXwNy3hUfrhzQyaEjDTJnx3+1+ono1orSazPO
Fr2RSsC5VzX4IYSuxTMvFSKjN1Iiu8xqwq3IdclHXrBhRvwOF2wpjjQ5Guf0lHBJ
FLBahSjZqt01kmwFykxoHps+VeSwpoEen6rClBQolfmtYVDTvgRNN46AxK9jZ8T4
jZmCNNs/mYzrqo/RTnmw
=u38W
-----END PGP SIGNATURE-----
Merge tag 'docs-4.5' of git://git.lwn.net/linux
Pull documentation updates from Jon Corbet:
"A relatively boring cycle in the docs tree. There's a few kernel-doc
fixes and various document tweaks.
One patch reaches out of the documentation subtree to fix a comment in
init/do_mounts_rd.c. There didn't seem to be anybody more appropriate
to take that one, so I accepted it"
* tag 'docs-4.5' of git://git.lwn.net/linux: (29 commits)
thermal: add description for integral_cutoff unit
Documentation: update libhugetlbfs site url
Documentation: Explain pci=conf1,conf2 more verbosely
DMA-API: fix confusing sentence in Documentation/DMA-API.txt
Documentation: translations: update linux cross reference link
Documentation: fix typo in CodingStyle
init, Documentation: Remove ramdisk_blocksize mentions
Documentation-getdelays: Apply a recommendation from "checkpatch.pl" in main()
Documentation: HOWTO: update versions from 3.x to 4.x
Documentation: remove outdated references from translations
Doc: treewide: Fix grammar "a" to "an"
Documentation: cpu-hotplug: Fix sysfs mount instructions
can-doc: Add hint about getting timestamps
Fix CFQ I/O scheduler parameter name in documentation
Documentation: arm: remove dead links from Marvell Berlin docs
Documentation: HOWTO: update code cross reference link
Doc: Docbook/iio: Fix typo in iio.tmpl
DocBook: make index.html generation less verbose by default
DocBook: Cleanup: remove an unused $(call) line
DocBook: Add a help message for DOCBOOKS env var
...
Some documented structures in the kernel use DECLARE_BITMAP to create
arrays of unsigned longs to store information using the bitmap functions.
These have to be replaced with a parsable version for kernel-doc.
For example a simple input like
/**
* struct something - some test
* @members: active members
*/
struct something {
DECLARE_BITMAP(members, MAX_MEMBERS);
};
resulted in parsing warnings like
warning: No description found for parameter 'MAX_MEMBERS)'
warning: Excess struct/union/enum/typedef member 'members' description in 'something'
Signed-off-by: Conchúr Navid <conchur@web.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Some enumerations in the kernel headers use #ifdef to reduce their size
based on the the configuration. These lines have to be stripped to avoid
parsing problems.
For example a simple input like
/**
* enum flags - test flags
* @flag1: first flag
* @flag2: second flag
*/
enum flags {
flag1 = BIT(0),
#ifdef SECOND_FLAG
flag2 = BIT(1),
#endif
};
resulted in parsing warnings like
warning: Enum value '#ifdef SECOND_FLAG;flag2 = BIT(1)' not described in enum 'flags'
warning: Enum value '#endif;' not described in enum 'flags'
Signed-off-by: Conchúr Navid <conchur@web.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The regex to strip single line #define's in enumerations depends on the
fact that the defines are still stored on separate lines. But the
surrounding code already removed newlines and replaced them with
semicolons.
For example a simple input like
/**
* enum flags - test flags
* @flag1: first flag
* @flag2: second flag
* @flag3: third flag
* @flag4: fourth flag
*/
enum flags {
flag1 = BIT(0),
flag2 = BIT(1),
#define flags_small (flag1 | flag2)
flag3 = BIT(2),
flag4 = BIT(3),
#define flags_big (flag2 | flag3)
};
resulted in parsing warnings like
warning: Enum value '#define flags_small (flag1 | flag2);flag3 = BIT(2)' not described in enum 'flags'
warning: Enum value '#define flags_big (flag2 | flag3);' not described in enum 'flags'
Signed-off-by: Conchúr Navid <conchur@web.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Changeset 4d73270192ec('scripts/kernel-doc: Replacing highlights
hash by an array') broke compatibility of the kernel-doc script with
older versions of perl by using "keys ARRAY" syntax with is available
only on Perl 5.12 or newer, according with:
http://perldoc.perl.org/functions/keys.html
Restore backward compatibility by replacing "foreach my $k (keys ARRAY)"
by a C-like variant: "for (my $k = 0; $k < !ARRAY; $k++)"
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
some new CAN driver documentation. Beyond that, we have kernel-doc fixes,
a bit more work to support reproducible builds, and the usual collection of
small fixes.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1
iQIcBAABAgAGBQJWO6HiAAoJEI3ONVYwIuV6ihwQAK0KC72h0706bdwDJ1p1/aJU
QLuPeiKYWgGAXq2zgOyw3Povj4bkMwkiq1IGHLyK0Id4tg3ngxOXjimk4YKrqarI
BD5HdpOm7IyQEe66ZU9b1RFDVst+bg3yp6ZIZsH5vQxl/KnyJ6AyaaDk8TPYId8S
1+CykJzxyi7GyT/jlLpHbKtBKrraoVke+cNPMAvOf0NjSyO7Ix5B+qH50sttG6Eu
9qcQ8hlKXOdZRTiGW6P+jeZNA+e5+CRpnG9VHBquHy4lI85kQThhWq41UMH690PP
eRbLipeUybb0FwW2KwuMjGKEMDkMvrGJh0TzSXX9lGHd+5/41v7zcyKh8vJcpLjh
bNQ2WOAKUBd2d15EP1MNoKXDLGJXusJczLwOjigWiSCQvgouAWwMrpWEw+Obv8Yl
rdoH1oQqDFfDnk6mnKrSaqLWGNuLxDtkEl/1P0jsGSK6lM3FDkOgTuNPYXTJJgxN
rXuGmPhyUlS2srERUeQJw2rISN0WRBvcKJGkMX6IpvrXHkItbelqK+yY1DeKPmcm
qgbIx9ZWNqtltFpG22VVByqAVwucO5Nu8cAIQ2ysJsTnKOvQCQmhu5UKTjBCkEJM
VpeMm32BfNiJFLuLTQGWBZ8bkRl2shQyXhOaR3uyqG4T+rpPD3qJi6dtFRpsAzOB
q1nZuJCpOaxJFzjSKvpJ
=emZ7
-----END PGP SIGNATURE-----
Merge tag 'docs-for-linus' of git://git.lwn.net/linux
Pull documentation update from Jon Corbet:
"There is a nice new document from Neil on how pathname lookups work
and some new CAN driver documentation. Beyond that, we have
kernel-doc fixes, a bit more work to support reproducible builds, and
the usual collection of small fixes"
* tag 'docs-for-linus' of git://git.lwn.net/linux: (34 commits)
Documentation: add new description of path-name lookup.
Documentation/vm/slub.txt: document slabinfo-gnuplot.sh
Doc: ABI/stable: Fix typo in ABI/stable
doc: Clarify that nmi_watchdog param is for hardlockups
Typo correction for description in gpio document.
DocBook: Fix kernel-doc to be case-insensitive for private:
kernel-docs.txt: update kernelnewbies reference
Doc:kvm: Fix typo in Doc/virtual/kvm
Documentation/Changes: Add bc in "Current Minimal Requirements" section
Documentation/email-clients.txt: remove trailing whitespace
DocBook: Use a fixed encoding for output
MAINTAINERS: The docs tree has moved
Docs/kernel-parameters: Add earlycon devicetree usage
SubmittingPatches: make Subject examples match the de facto standard
Documentation: gpio: mention that <function>-gpio has been deprecated
Documentation: cgroups: just fix a few typos
Documentation: Update kselftest.txt
Documentation: DMA API: Be more explicit that nents is always the same
Documentation: Update the default value of crashkernel low
zram: update documentation
...
On some places, people could use Private: to tag the private fields
of an struct. So, be case-insensitive when parsing "private:"
meta-tag.
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
A typedef function looks more likely a function and not a
normal typedef. Change the code to use the output_function_*,
in order to properly parse the function prototype parameters.
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
The current typedef parser only works for non-function typedefs.
As we need to also document some function typedefs, add a
parser for it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
The "highlight" code is very sensible to the order of the hash keys,
but the order of the keys cannot be predicted. It generates
faulty DocBook entries like:
- @<function>device_for_each_child</function>
Sorting the result is not enough some times (as it's deterministic but
we can't control it).
We should use an array for that job, so we can guarantee that the order
of the regex execution on dohighlight is correct.
[jc: I think this is kind of papering around the real problem, that people
are saying @function() when "function" is not a parameter. But this makes
things better than they were before, so...]
Signed-off-by: Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Currently kernel-doc generates a dummy DocBook file when asked to
convert a C source file with no structured comments. For an
out-of-tree build (objtree != srctree), the title of the output file
is the absolute path name of the C source file, which later results
in a manual page being created alongside the C source file.
Change the title to be a relative path.
Signed-off-by: Ben Hutchings <ben@decadent.org.uk>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Docproc processes the EXPORT_SYMBOL(f1) macro and uses -nofunc f1 to
avoid duplicated documentation in the next call.
It works for most of the cases, but there are some specific situations
where a struct has the same name of an already-exported function.
Current kernel-doc behavior ignores those structs and does not add them
to the final documentation. This patch fixes it.
This is unusual, the only case I've found is the drm_modeset_lock
(function and struct) defined in drm_modeset_lock.h and
drm_modeset_lock.c. Considering this, it should only affect the DRM
documentation by including struct drm_modeset_lock to the final Docbook.
Signed-off-by: Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Editors like emacs and vi recognize a number of error message formats.
The format used by the kerneldoc tool is not recognized by emacs.
Change the kerneldoc error message format to the GNU style such that the
emacs prev-error and next-error commands can be used to navigate through
kerneldoc error messages. For more information about the GNU error
message format, see also
https://www.gnu.org/prep/standards/html_node/Errors.html.
This patch has been generated via the following sed command:
sed -i.orig 's/Error(\${file}:\$.):/\${file}:\$.: error:/g;s/Warning(\${file}:\$.):/\${file}:\$.: warning:/g;s/Warning(\${file}):/\${file}:1: warning:/g;s/Info(\${file}:\$.):/\${file}:\$.: info:/g' scripts/kernel-doc
Signed-off-by: Bart Van Assche <bart.vanassche@sandisk.com>
Cc: Johannes Berg <johannes.berg@intel.com>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
The kernel-doc script gets confused by __attribute__(()) strings in
structures, so just clean the out. Also ignore the CRYPTO_MINALIGN_ATTR
macro used in the crypto subsystem.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Describing arguments at top of a struct definition works fine
for small/medium size structs, but it definitely doesn't work well
for struct with a huge list of elements.
Keeping the arguments list inside the struct body makes it easier
to maintain the documentation.
ie:
/**
* struct my_struct - short description
* @a: first member
* @b: second member
*
* Longer description
*/
struct my_struct {
int a;
int b;
/**
* @c: This is longer description of C
*
* You can use paragraphs to describe arguments
* using this method.
*/
int c;
};
This patch allows the use of this kind of syntax. Only one argument
per comment and user can use how many paragraphs he needs. It should
start with /**, which is already being used by kernel-doc. If those
comment doesn't follow those rules, it will be ignored.
Signed-off-by: Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk>
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Herbert Xu <herbert@gondor.apana.org.au>
Cc: Stephan Mueller <smueller@chronox.de>
Cc: Michal Marek <mmarek@suse.cz>
Cc: linux-kernel@vger.kernel.org
Cc: linux-doc@vger.kernel.org
Cc: intel-gfx <intel-gfx@lists.freedesktop.org>
Cc: dri-devel <dri-devel@lists.freedesktop.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Together with the preceding changes, this allows man pages to be built
reproducibly.
Signed-off-by: Ben Hutchings <ben@decadent.org.uk>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Regular expressions for highlights in kernel-doc are stored in a Perl
hash. These hashes are ordered differently for each Perl run. This will
prevent kernel-doc to behave deterministically when parsing “@foo()” as
in some runs it will be interpreted as a parameter and in the others it
will be interpreted as a function.
We now sort the %highlights hash to get the same behavior on every run.
Signed-off-by: Jérémy Bobbio <lunar@debian.org>
Signed-off-by: Ben Hutchings <ben@decadent.org.uk>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The change from \d+ to .+ inside __aligned() means that the following
structure:
struct test {
u8 a __aligned(2);
u8 b __aligned(2);
};
essentially gets modified to
struct test {
u8 a;
};
for purposes of kernel-doc, thus dropping a struct member, which in
turns causes warnings and invalid kernel-doc generation.
Fix this by replacing the catch-all (".") with anything that's not a
semicolon ("[^;]").
Fixes: 9dc30918b2 ("scripts/kernel-doc: handle struct member __aligned without numbers")
Signed-off-by: Johannes Berg <johannes.berg@intel.com>
Cc: Nishanth Menon <nm@ti.com>
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Michal Marek <mmarek@suse.cz>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Fix scripts/kernel-doc to recognize __meminit in a function prototype
and to strip it, as done with many other attributes.
Fixes this warning:
Warning(..//mm/page_alloc.c:2973): cannot understand function prototype: 'void * __meminit alloc_pages_exact_nid(int nid, size_t size, gfp_t gfp_mask) '
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Object-like macros are different than function-like macros:
https://gcc.gnu.org/onlinedocs/cpp/Object-like-Macros.htmlhttps://gcc.gnu.org/onlinedocs/cpp/Function-like-Macros.html
They are not parsed correctly, generating invalid intermediate
files (xmls) for cases like:
#define BIT_MASK (0xFF << BIT_SHIFT)
where "OxFF <<" is considered to be parameter type.
When parsing, we can differentiate beween these two types of macros by
checking whether there is at least one whitespace b/w "#define" and
first opening parenthesis.
Signed-off-by: Horia Geanta <horia.geanta@freescale.com>
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Pull misc kbuild changes from Michal Marek:
- make tags fixes again
- scripts/show_delta fix for newer python
- scripts/kernel-doc does not fail on unknown function prototype
- one less coccinelle check this time
* 'misc' of git://git.kernel.org/pub/scm/linux/kernel/git/mmarek/kbuild:
scripts/tags.sh: remove obsolete __devinit[const|data]
scripts/kernel-doc: make unknown function prototype a Warning instead of an Error
show_delta: Update script to support python versions 2.5 through 3.3
scripts/coccinelle/api: remove devm_request_and_ioremap.cocci
scripts/tags.sh: Increase identifier list
When using '!Ffile function' in a docbook template, and the function no
longer exists, you get a "no structured comments found" error from the
kernel-doc processing script. It's useful to know which functions it was
looking for, so print them out in this case. Also do the same for '!Pfile
doc-section'
The same error also happens when using '!Efile' when some exported
functions aren't documented (in the same file.) There's a very large
number of such functions though, so don't print the message in this case
-- right now it would give ~850 messages.
Signed-off-by: Johannes Berg <johannes.berg@intel.com>
Cc: Rob Landley <rob@landley.net>
Cc: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
When scripts/kernel-doc cannot understand a function prototype,
it had been generating a fatal error and stopping immediately.
Make this a Warning instead of an Error and keep going.
Note that this can happen if the kernel-doc notation that is being
parsed is not actually a function prototype; maybe it's a struct or
something else, so I added "function" to the warning message to try
to make it clearer that scripts/kernel-doc is looking for a function
prototype here.
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Mark Brown <broonie@kernel.org>
Signed-off-by: Michal Marek <mmarek@suse.cz>
Commit ef5da59f12 ("scripts/kernel-doc: handle struct member
__aligned") permits "char something [123] __aligned(8);".
However, by using \d we constraint ourselves with integers. This is not
always the case. In fact, it might be better to do char something[123]
__aligned(sizeof(u16));
For example, With wireless_dev defining:
u8 address[ETH_ALEN] __aligned(sizeof(u16));
With \d, scripts/kernel-doc erroneously says:
Warning(include/net/cfg80211.h:2618): Excess struct/union/enum/typedef member 'address' description in 'wireless_dev'
This is because the regex __aligned\s*\(\d+\) fails match at \d as
sizeof is used.
So replace \d with . to indicate "something" in kernel-doc to ignore
__aligned(SOMETHING) in structs. With this change, we can use integers
OR sizeof() or macros as we please.
Signed-off-by: Nishanth Menon <nm@ti.com>
Cc: Fengguang Wu <fengguang.wu@intel.com>
Cc: Johannes Berg <johannes.berg@intel.com>
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Michal Marek <mmarek@suse.cz>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
CONFIG_HOTPLUG is going away as an option. As a result, the __dev*
markings need to be removed.
This change removes the last of the __dev* markings from the kernel from
a variety of different, tiny, places.
Based on patches originally written by Bill Pemberton, but redone by me
in order to handle some of the coding style issues better, by hand.
Cc: Bill Pemberton <wfp5p@virginia.edu>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
If a function has a return value, but its kernel-doc comment doesn't contain a
"Return" section, then emit the following warning:
Warning(file.h:129): No description found for return value of 'fct'
Note: This check emits a lot of warnings at the moment, because many functions
don't have a 'Return' doc section. So until the number of warnings goes
sufficiently down, the check is only performed in verbose mode.
Signed-off-by: Yacine Belkadi <yacine.belkadi.1@gmail.com>
Signed-off-by: Rob Landley <rob@landley.net>
Signed-off-by: Jiri Kosina <jkosina@suse.cz>
Pull kbuild misc changes from Michal Marek:
"In the non-critical part of kbuild, I have
- Some make coccicheck improvements and two new tests
- Support for a cleaner html output in scripts/kernel-doc, named
html5 (no, it does not play videos, yet)
BTW, Randy wants to route further kernel-doc patches through the
kbuild tree."
* 'misc' of git://git.kernel.org/pub/scm/linux/kernel/git/mmarek/kbuild:
Update SmPL/Coccinelle section of MAINTAINERS
coccicheck: Add the rep+ctxt mode
scripts/coccinelle/tests/odd_ptr_err.cocci: semantic patch for IS_ERR/PTR_ERR inconsistency
scripts/tags.sh: Add magic for pci access functions
scripts/coccinelle: ptr_ret: Add ternary operator version
scripts/kernel-doc: drop maintainer
scripts/kernel-doc: added support for html5
A section with the name "Example" (case-insensitive) has a special meaning
to kernel-doc. These sections are output using mono-type fonts. However,
leading whitespace is stripped, thus robbing a lot of meaning from this,
as indented code examples will be mangled.
This patch preserves the leading whitespace for "Example" sections. More
accurately, it preserves it for all sections, but removes it later if the
section isn't an "Example" section.
Signed-off-by: Daniel Santos <daniel.santos@pobox.com>
Cc: Randy Dunlap <rdunlap@xenotime.net>
Cc: Michal Marek <mmarek@suse.cz>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
If you have a section named "Example" that contains an empty line,
attempting to generate htmldocs give you the error:
/path/Documentation/DocBook/kernel-api.xml:3455: parser error : Opening and ending tag mismatch: programlisting line 3449 and para
</para><para>
^
/path/Documentation/DocBook/kernel-api.xml:3473: parser error : Opening and ending tag mismatch: para line 3467 and programlisting
</programlisting></informalexample>
^
/path/Documentation/DocBook/kernel-api.xml:3678: parser error : Opening and ending tag mismatch: programlisting line 3672 and para
</para><para>
^
/path/Documentation/DocBook/kernel-api.xml:3701: parser error : Opening and ending tag mismatch: para line 3690 and programlisting
</programlisting></informalexample>
^
unable to parse
/path/Documentation/DocBook/kernel-api.xml
Essentially, the script attempts to close a <programlisting> with a
closing tag for a <para> block. This patch corrects the problem by
simply not outputting anything extra when we're dumping pre-formatted
text, since the empty line will be rendered correctly anyway.
Signed-off-by: Daniel Santos <daniel.santos@pobox.com>
Cc: Randy Dunlap <rdunlap@xenotime.net>
Cc: Michal Marek <mmarek@suse.cz>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Prior to this patch the following code breaks:
/**
* multiline_example - this breaks kernel-doc
*/
#define multiline_example( \
myparam)
Producing this error:
Error(somefile.h:983): cannot understand prototype: 'multiline_example( \ '
This patch fixes the issue by appending all lines ending in a blackslash
(optionally followed by whitespace), removing the backslash and any
whitespace after it prior to appending (just like the C pre-processor
would).
This fixes a break in kerel-doc introduced by the additions to rbtree.h.
Signed-off-by: Daniel Santos <daniel.santos@pobox.com>
Cc: Randy Dunlap <rdunlap@xenotime.net>
Cc: Michal Marek <mmarek@suse.cz>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
New output option html5 writes validating HTML5 and adds
CSS classes ready to be selected by third-party stylesheets.
HTML ids have been added to block-level elements "article" for
direct reference of particular objects via URL.
Signed-off-by: Dan Luedtke <mail@danrl.de>
Acked-by: Randy Dunlap <rdunlap@xenotime.net>
Signed-off-by: Michal Marek <mmarek@suse.cz>
include/net/cfg80211.h uses __must_check in functions that
have kernel-doc notation. This was confusing scripts/kernel-doc,
so have scripts/kernel-doc ignore "__must_check".
Error(include/net/cfg80211.h:2702): cannot understand prototype: 'struct cfg80211_bss * __must_check cfg80211_inform_bss(...)
Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
Cc: Johannes Berg <johannes@sipsolutions.net>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Move 'main' code vs. subroutines around so that they are not so
intermixed, for better readability/understanding (relative to Perl).
It was messy to follow the primary flow of code execution with the
code being mixed. Now the code begins with data initialization,
followed by all subroutines, then ends with the main code execution.
This is almost totally source code movement, with a few changes as
needed for forward declarations.
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
scripts/kernel-doc was leaving unescaped '<', '>', and '&' in
generated xml output for structs. This causes xml parser errors.
Convert these characters to "<", ">", and "&" as needed
to prevent errors.
Most of the conversion was already done; complete it just before
output.
Documentation/DocBook/device-drivers.xml:41883: parser error : StartTag: invalid element name
#define INPUT_KEYMAP_BY_INDEX (1 << 0)
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
When you don't use !E or !I but only !F, then it's very easy to miss
including some functions, structs etc. in documentation. To help
finding which ones were missed, allow printing out the unused ones as
warnings.
For example, using this on mac80211 yields a lot of warnings like this:
Warning: didn't use docs for DOC: mac80211 workqueue
Warning: didn't use docs for ieee80211_max_queues
Warning: didn't use docs for ieee80211_bss_change
Warning: didn't use docs for ieee80211_bss_conf
when generating the documentation for it.
Signed-off-by: Johannes Berg <johannes.berg@intel.com>
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
There are valid attributes that could have upper case letters, but we
still want to remove, like for example
__attribute__((aligned(NETDEV_ALIGN)))
as encountered in the wireless code.
Signed-off-by: Johannes Berg <johannes.berg@intel.com>
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Fix mtd/nand_base.c kernel-doc warnings and typos.
Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'mtd'
Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'ofs'
Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'len'
Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'invert'
Warning(drivers/mtd/nand/nand_base.c:930): No description found for parameter 'mtd'
Warning(drivers/mtd/nand/nand_base.c:930): No description found for parameter 'ofs'
Warning(drivers/mtd/nand/nand_base.c:930): No description found for parameter 'len'
Warning(drivers/mtd/nand/nand_base.c:987): No description found for parameter 'mtd'
Warning(drivers/mtd/nand/nand_base.c:987): No description found for parameter 'ofs'
Warning(drivers/mtd/nand/nand_base.c:987): No description found for parameter 'len'
Warning(drivers/mtd/nand/nand_base.c:2087): No description found for parameter 'len'
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Cc: David Woodhouse <dwmw2@infradead.org>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
