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 <[email protected]>
Cc: Fengguang Wu <[email protected]>
Cc: Johannes Berg <[email protected]>
Cc: Randy Dunlap <[email protected]>
Cc: Michal Marek <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

misc: remove __dev* attributes.

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

misc: remove __dev* attributes.

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 <[email protected]>
Signed-off-by: Greg Kroah-Hartman <[email protected]>

show more ...

scripts/kernel-doc: check that non-void fcts describe their return value

If a function has a return value, but its kernel-doc comment doesn't contain a
"Return" section, then emit the following warn

scripts/kernel-doc: check that non-void fcts describe their return value

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 <[email protected]>
Acked-by: Randy Dunlap <[email protected]>
Signed-off-by: Michal Marek <[email protected]>

show more ...

scripts/kernel-doc: check that non-void fcts describe their return value

If a function has a return value, but its kernel-doc comment doesn't contain a
"Return" section, then emit the following warn

scripts/kernel-doc: check that non-void fcts describe their return value

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 <[email protected]>
Signed-off-by: Rob Landley <[email protected]>
Signed-off-by: Jiri Kosina <[email protected]>

show more ...

kernel-doc: don't mangle whitespace in Example section

A section with the name "Example" (case-insensitive) has a special meaning
to kernel-doc. These sections are output using mono-type fonts. Ho

kernel-doc: don't mangle whitespace in Example section

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 <[email protected]>
Cc: Randy Dunlap <[email protected]>
Cc: Michal Marek <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

kernel-doc: bugfix - empty line in Example section

If you have a section named "Example" that contains an empty line,
attempting to generate htmldocs give you the error:

/path/Documentation/DocBook

kernel-doc: bugfix - empty line in Example section

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 <[email protected]>
Cc: Randy Dunlap <[email protected]>
Cc: Michal Marek <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

kernel-doc: bugfix - multi-line macros

Prior to this patch the following code breaks:

/**
* multiline_example - this breaks kernel-doc
*/
#define multiline_example( \
myparam)

Producing this er

kernel-doc: bugfix - multi-line macros

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 <[email protected]>
Cc: Randy Dunlap <[email protected]>
Cc: Michal Marek <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

scripts/kernel-doc: added support for html5

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-le

scripts/kernel-doc: added support for html5

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 <[email protected]>
Acked-by: Randy Dunlap <[email protected]>
Signed-off-by: Michal Marek <[email protected]>

show more ...

scripts/kernel-doc: fix fatal script error

Fix fatal error in scripts/kernel-doc by ignoring the "__weak" attribute:

Error(drivers/pci/pci.c:2820): cannot understand prototype: 'char * __weak pci

scripts/kernel-doc: fix fatal script error

Fix fatal error in scripts/kernel-doc by ignoring the "__weak" attribute:

Error(drivers/pci/pci.c:2820): cannot understand prototype: 'char * __weak pcibios_setup(char *str) '

Signed-off-by: Randy Dunlap <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

scripts/kernel-doc: fix fatal error caused by cfg80211.h

include/net/cfg80211.h uses __must_check in functions that
have kernel-doc notation. This was confusing scripts/kernel-doc,
so have scripts/

scripts/kernel-doc: fix fatal error caused by cfg80211.h

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 <[email protected]>
Cc: Johannes Berg <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

Fix common misspellings

Fixes generated by 'codespell' and manually reviewed.

Signed-off-by: Lucas De Marchi <[email protected]>

kernel-doc: code reorganization

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 primar

kernel-doc: code reorganization

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

show more ...

kernel-doc: escape xml for structs

scripts/kernel-doc was leaving unescaped '<', '>', and '&' in
generated xml output for structs. This causes xml parser errors.
Convert these characters to "&lt;",

kernel-doc: escape xml for structs

scripts/kernel-doc was leaving unescaped '<', '>', and '&' in
generated xml output for structs. This causes xml parser errors.
Convert these characters to "&lt;", "&gt;", and "&amp;" 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 <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

docbook: warn on unused doc entries

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 mi

docbook: warn on unused doc entries

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 <[email protected]>
Signed-off-by: Randy Dunlap <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

kernel-doc: ignore case when stripping attributes

There are valid attributes that could have upper case letters, but we
still want to remove, like for example
__attribute__((aligned(NETDEV_ALIGN)))

kernel-doc: ignore case when stripping attributes

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 <[email protected]>
Signed-off-by: Randy Dunlap <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

mtd/nand_base: fix kernel-doc warnings & typos

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_base: fix kernel-doc warnings & typos

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 <[email protected]>
Cc: David Woodhouse <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

mtd/nand_base: fix kernel-doc warnings & typos

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_base: fix kernel-doc warnings & typos

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

show more ...

scripts/kernel-doc: fix fatal error on function prototype

Fix a fatal error in scripts/kernel-doc when a function signature uses
__init_or_module (just ignore that string):

Error(drivers/base/platf

scripts/kernel-doc: fix fatal error on function prototype

Fix a fatal error in scripts/kernel-doc when a function signature uses
__init_or_module (just ignore that string):

Error(drivers/base/platform.c:568): cannot understand prototype: 'struct platform_device * __init_or_module platform_create_bundle(struct platform_driver *driver, int (*probe)(struct platform_device *), struct resource *res, unsigned int n_res, const void *data, size_t size) '

Signed-off-by: Randy Dunlap <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

scripts/kernel-doc: handle struct member __aligned

scripts/kernel-doc erroneously says:

Warning(include/linux/skbuff.h:410): Excess struct/union/enum/typedef member 'cb' description in 'sk_buff'

o

scripts/kernel-doc: handle struct member __aligned

scripts/kernel-doc erroneously says:

Warning(include/linux/skbuff.h:410): Excess struct/union/enum/typedef member 'cb' description in 'sk_buff'

on this line in struct sk_buff:
char cb[48] __aligned(8);

due to treating the last field as the struct member name, so teach
kernel-doc to ignore __aligned(x) in structs.

Signed-off-by: Randy Dunlap <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

scripts/kernel-doc: fix empty function description section

scripts/kernel-doc mishandles a function that has a multi-line function
short description and no function parameters. The observed problem

scripts/kernel-doc: fix empty function description section

scripts/kernel-doc mishandles a function that has a multi-line function
short description and no function parameters. The observed problem was
from drivers/scsi/scsi_netlink.c:

/**
* scsi_netlink_init - Called by SCSI subsystem to intialize
* the SCSI transport netlink interface
*
**/

kernel-doc treated the " * " line as a Description: section with only a
newline character in the Description contents. This caused
output_highlight() to complain: "output_highlight got called with no
args?", plus produce a perl call stack backtrace.

The fix is just to ignore Description sections if they only contain "\n".

Signed-off-by: Randy Dunlap <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

kernel-doc: drop the -filelist option, it doesn't work

I also found the -filelist option, but apparently the implementation
is broken, and it was broken from the very first git commit.
For the -file

kernel-doc: drop the -filelist option, it doesn't work

I also found the -filelist option, but apparently the implementation
is broken, and it was broken from the very first git commit.
For the -filelist option I suggest the removal (I wasn't able to find
any users of it, moreover it's not even listed in the
usage() output, so presumably nobody knows about it).

Signed-off-by: Ilya Dryomov <[email protected]>
Signed-off-by: Randy Dunlap <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

kernel-doc: track line numbers for each file separately

The problem is that $. keeps track of the current record number (which
is line number by default). But if you pass it multiple files, it does

kernel-doc: track line numbers for each file separately

The problem is that $. keeps track of the current record number (which
is line number by default). But if you pass it multiple files, it does
not wrap at the end of file, and therefore contains the *total* number
of processed lines.
I suppose we can fix line numbering by introducing a simple assignment
$. = 1
before processing every new file.

Signed-off-by: Ilya Dryomov <[email protected]>
Signed-off-by: Randy Dunlap <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

tracing: Add DEFINE_EVENT(), DEFINE_SINGLE_EVENT() support to docbook

The introduction of the new 'DECLARE_EVENT_CLASS()' obviates the
need for the 'TRACE_EVENT()' macro in some cases. Thus, docbook

tracing: Add DEFINE_EVENT(), DEFINE_SINGLE_EVENT() support to docbook

The introduction of the new 'DECLARE_EVENT_CLASS()' obviates the
need for the 'TRACE_EVENT()' macro in some cases. Thus, docbook
style comments that used to live with 'TRACE_EVENT()' are now
moved to 'DEFINE_EVENT()'. Thus, we need to make the docbook
system understand the new 'DEFINE_EVENT()' macro. In addition
I've tried to futureproof the patch, by also adding support for
'DEFINE_SINGLE_EVENT()', since there has been discussion about
renaming: TRACE_EVENT() -> DEFINE_SINGLE_EVENT().

Without this patch the tracepoint docbook fails to build.

I've verified that this patch correctly builds the tracepoint
docbook which currently covers signals, and irqs.

Changes in v2:
- properly indent perl 'if' statements

Signed-off-by: Jason Baron <[email protected]>
Acked-by: Steven Rostedt <[email protected]>
Acked-by: Randy Dunlap <[email protected]>
Cc: William Cohen <[email protected]>
Cc: Frederic Weisbecker <[email protected]>
Cc: Mathieu Desnoyers <[email protected]>
Cc: Masami Hiramatsu <[email protected]>
LKML-Reference: <200912011718.nB1HIn7t011371@int-mx04.intmail.prod.int.phx2.redhat.com>
Signed-off-by: Ingo Molnar <[email protected]>

show more ...

kernel-doc: allow multi-line declaration purpose descriptions

Allow the short description after symbol name and dash in a kernel-doc
comment to span multiple lines, e.g. like this:

/**
* unmap_m

kernel-doc: allow multi-line declaration purpose descriptions

Allow the short description after symbol name and dash in a kernel-doc
comment to span multiple lines, e.g. like this:

/**
* unmap_mapping_range - unmap the portion of all mmaps in the
* specified address_space corresponding to the specified
* page range in the underlying file.
* @mapping: the address space containing mmaps to be unmapped.
* ...
*/

The short description ends with a parameter description, an empty line
or the end of the comment block.

Signed-off-by: Johannes Weiner <[email protected]>
Signed-off-by: Randy Dunlap <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

kernel-doc: move ignoring kmemcheck

Somehow I managed to generate a diff that put these 2 lines
into the wrong function: should have been in dump_struct()
instead of in dump_enum().

Signed-off-by:

kernel-doc: move ignoring kmemcheck

Somehow I managed to generate a diff that put these 2 lines
into the wrong function: should have been in dump_struct()
instead of in dump_enum().

Signed-off-by: Randy Dunlap <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...