kernel-doc: use rst C domain directives and references for types

First, the headings for structs, enums and typedefs will be similar to
functions. Second, this provides a kind of namespace for cross

kernel-doc: use rst C domain directives and references for types

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>

show more ...

kernel-doc: produce RestructuredText output

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 headi

kernel-doc: produce RestructuredText output

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>

show more ...

kernel-doc: rewrite usage description, remove duplicated comments

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,

kernel-doc: rewrite usage description, remove duplicated comments

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>

show more ...

kernel-doc: Fix parsing of DECLARE_BITMAP in struct

Some documented structures in the kernel use DECLARE_BITMAP to create
arrays of unsigned longs to store information using the bitmap functions.
Th

kernel-doc: Fix parsing of DECLARE_BITMAP in struct

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>

show more ...

kernel-doc: Strip #ifdef/#endif in enums

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 prob

kernel-doc: Strip #ifdef/#endif in enums

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>

show more ...

kernel-doc: Fix stripping of #define in enums

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 co

kernel-doc: Fix stripping of #define in enums

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>

show more ...

kernel-doc: Make it compatible with Perl versions below 5.12 again

Changeset 4d73270192ec('scripts/kernel-doc: Replacing highlights
hash by an array') broke compatibility of the kernel-doc script wi

kernel-doc: Make it compatible with Perl versions below 5.12 again

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>

show more ...

DocBook: Fix kernel-doc to be case-insensitive for private:

On some places, people could use Private: to tag the private fields
of an struct. So, be case-insensitive when parsing "private:"
meta-tag

DocBook: Fix kernel-doc to be case-insensitive for private:

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>

show more ...

kernel-doc: better format typedef function output

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 t

kernel-doc: better format typedef function output

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>

show more ...

kernel-doc: Add a parser for function typedefs

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-

kernel-doc: Add a parser for function typedefs

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>

show more ...

scripts/kernel-doc: Replacing highlights hash by an array

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 DocB

scripts/kernel-doc: Replacing highlights hash by an array

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>

show more ...

Documentation: Avoid creating man pages in source tree

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 buil

Documentation: Avoid creating man pages in source tree

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>

show more ...

scripts/kernel-doc: Processing -nofunc for functions only

Docproc processes the EXPORT_SYMBOL(f1) macro and uses -nofunc f1 to
avoid duplicated documentation in the next call.
It works for most of t

scripts/kernel-doc: Processing -nofunc for functions only

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>

show more ...

kerneldoc: Convert error messages to GNU error message format

Editors like emacs and vi recognize a number of error message formats.
The format used by the kerneldoc tool is not recognized by emacs.

kerneldoc: Convert error messages to GNU error message format

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>

show more ...

kernel-doc: ignore unneeded attribute information

The kernel-doc script gets confused by __attribute__(()) strings in
structures, so just clean the out. Also ignore the CRYPTO_MINALIGN_ATTR
macro u

kernel-doc: ignore unneeded attribute information

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>

show more ...

scripts/kernel-doc Allow struct arguments documentation in struct body

Describing arguments at top of a struct definition works fine
for small/medium size structs, but it definitely doesn't work wel

scripts/kernel-doc Allow struct arguments documentation in struct body

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>

show more ...

scripts/kernel-doc: Use $KBUILD_BUILD_TIMESTAMP as man page date

Together with the preceding changes, this allows man pages to be built
reproducibly.

Signed-off-by: Ben Hutchings <ben@decadent.org.

scripts/kernel-doc: Use $KBUILD_BUILD_TIMESTAMP as man page date

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>

show more ...

scripts/kernel-doc: parse kernel-doc deterministically

Regular expressions for highlights in kernel-doc are stored in a Perl
hash. These hashes are ordered differently for each Perl run. This will

scripts/kernel-doc: parse kernel-doc deterministically

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>

show more ...

scripts/kernel-doc: don't eat struct members with __aligned

The change from \d+ to .+ inside __aligned() means that the following
structure:

struct test {
u8 a __aligned(2);
u8 b

scripts/kernel-doc: don't eat struct members with __aligned

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: 9dc30918b23f ("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>

show more ...

scripts/kernel-doc: recognize __meminit

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(../

scripts/kernel-doc: recognize __meminit

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>

show more ...

scripts/kernel-doc: handle object-like macros

Object-like macros are different than function-like macros:
https://gcc.gnu.org/onlinedocs/cpp/Object-like-Macros.html
https://gcc.gnu.org/onlinedocs/cp

scripts/kernel-doc: handle object-like macros

Object-like macros are different than function-like macros:
https://gcc.gnu.org/onlinedocs/cpp/Object-like-Macros.html
https://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>

show more ...

scripts/kernel-doc: make unknown function prototype a Warning instead of an Error

When scripts/kernel-doc cannot understand a function prototype,
it had been generating a fatal error and stopping im

scripts/kernel-doc: make unknown function prototype a Warning instead of an Error

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>
Acked-by: Mark Brown <broonie@kernel.org>
Acked-by: Rob Landley <rob@landley.net>
Signed-off-by: Jiri Kosina <jkosina@suse.cz>

show more ...

kernel-doc: improve "no structured comments found" error

When using '!Ffile function' in a docbook template, and the function no
longer exists, you get a "no structured comments found" error from th

kernel-doc: improve "no structured comments found" error

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>

show more ...

scripts/kernel-doc: make unknown function prototype a Warning instead of an Error

When scripts/kernel-doc cannot understand a function prototype,
it had been generating a fatal error and stopping im

scripts/kernel-doc: make unknown function prototype a Warning instead of an Error

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>

show more ...

scripts/kernel-doc: handle struct member __aligned without numbers

Commit ef5da59f1260 ("scripts/kernel-doc: handle struct member
__aligned") permits "char something [123] __aligned(8);".

However,

scripts/kernel-doc: handle struct member __aligned without numbers

Commit ef5da59f1260 ("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>

show more ...