kernel-doc: fix param matching for array params

Fix function actual parameter vs. kernel-doc description matching
so that a warning is not printed when it should not be:

Warning(include/linux/ether

kernel-doc: fix param matching for array params

Fix function actual parameter vs. kernel-doc description matching
so that a warning is not printed when it should not be:

Warning(include/linux/etherdevice.h:199): Excess function parameter 'addr' description in 'is_etherdev_addr'

Signed-off-by: Randy Dunlap <[email protected]>
Signed-off-by: Sam Ravnborg <[email protected]>

show more ...

kernel-doc: ignore kmemcheck_bitfield_begin/end

Teach kernel-doc to ignore kmemcheck_bitfield_{begin,end} sugar
so that it won't generate warnings like this:

Warning(include/net/sock.h:297): No des

kernel-doc: ignore kmemcheck_bitfield_begin/end

Teach kernel-doc to ignore kmemcheck_bitfield_{begin,end} sugar
so that it won't generate warnings like this:

Warning(include/net/sock.h:297): No description found for parameter 'kmemcheck_bitfield_begin(flags)'
Warning(include/net/sock.h:297): No description found for parameter 'kmemcheck_bitfield_end(flags)'

Signed-off-by: Randy Dunlap <[email protected]>
Signed-off-by: Sam Ravnborg <[email protected]>

show more ...

kernel-doc: cleanup perl script

Various cleanups of scripts/kernel-doc:
- don't use **/ as an ending kernel-doc block since it's not preferred;
- typos/spellos
- add whitespace around ==, after comm

kernel-doc: cleanup perl script

Various cleanups of scripts/kernel-doc:
- don't use **/ as an ending kernel-doc block since it's not preferred;
- typos/spellos
- add whitespace around ==, after comma, & around . operator;

Signed-off-by: Randy Dunlap <[email protected]>
Signed-off-by: Sam Ravnborg <[email protected]>

show more ...

kernel-doc: restrict syntax for private: and public:

scripts/kernel-doc can (incorrectly) delete struct members that are
surrounded by /* ... */ <struct members> /* ... */ if there is a /*
private

kernel-doc: restrict syntax for private: and public:

scripts/kernel-doc can (incorrectly) delete struct members that are
surrounded by /* ... */ <struct members> /* ... */ if there is a /*
private: */ comment in there somewhere also.

Fix that by making the "/* private:" only allow whitespace between /* and
"private:", not anything/everything in the world.

This fixes some erroneous kernel-doc warnings that popped up while
processing include/linux/usb/composite.h.

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

show more ...

kerneldoc, tracing: make kernel-doc understand TRACE_EVENT() macro (take #2)

Add support to kernel-doc for tracepoint comments above TRACE_EVENT()
macro definitions. Paves the way for tracepoint doc

kerneldoc, tracing: make kernel-doc understand TRACE_EVENT() macro (take #2)

Add support to kernel-doc for tracepoint comments above TRACE_EVENT()
macro definitions. Paves the way for tracepoint docbook.

[ Impact: extend DocBook infrastructure ]

Signed-off-by: Jason Baron <[email protected]>
Acked-by: Randy Dunlap <[email protected]>
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
LKML-Reference: <d80706b6797e277924d2f3ec9af176c6b2951f88.1241107197.git.jbaron@redhat.com>
Signed-off-by: Ingo Molnar <[email protected]>

show more ...

kernel-doc: fix syscall wrapper processing

Fix kernel-doc processing of SYSCALL wrappers.

The SYSCALL wrapper patches played havoc with kernel-doc for
syscalls. Syscalls that were scanned for DocB

kernel-doc: fix syscall wrapper processing

Fix kernel-doc processing of SYSCALL wrappers.

The SYSCALL wrapper patches played havoc with kernel-doc for
syscalls. Syscalls that were scanned for DocBook processing
reported warnings like this one, for sys_tgkill:

Warning(kernel/signal.c:2285): No description found for parameter 'tgkill'
Warning(kernel/signal.c:2285): No description found for parameter 'pid_t'
Warning(kernel/signal.c:2285): No description found for parameter 'int'

because the macro parameters all "look like" function parameters,
although they are not:

/**
* sys_tgkill - send signal to one specific thread
* @tgid: the thread group ID of the thread
* @pid: the PID of the thread
* @sig: signal to be sent
*
* This syscall also checks the @tgid and returns -ESRCH even if the PID
* exists but it's not belonging to the target process anymore. This
* method solves the problem of threads exiting and PIDs getting reused.
*/
SYSCALL_DEFINE3(tgkill, pid_t, tgid, pid_t, pid, int, sig)
{
...

This patch special-cases the handling SYSCALL_DEFINE* function
prototypes by expanding them to
long sys_foobar(type1 arg1, type1 arg2, ...)

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: check for extra kernel-doc notations

Add functionality to check for function parameters or structure (or
union/typedef/enum) field members that are described in kernel-doc but
are not pa

kernel-doc: check for extra kernel-doc notations

Add functionality to check for function parameters or structure (or
union/typedef/enum) field members that are described in kernel-doc but
are not part of the expected (declared) parameters or structure.
These generate warnings that are called "Excess" descriptions.

Signed-off-by: Randy Dunlap <[email protected]>
Signed-off-by: Sam Ravnborg <[email protected]>

show more ...

kernel-doc: handle varargs cleanly

The method for listing varargs in kernel-doc notation is:
* @...: these arguments are printed by the @fmt argument

but scripts/kernel-doc is confused: it always

kernel-doc: handle varargs cleanly

The method for listing varargs in kernel-doc notation is:
* @...: these arguments are printed by the @fmt argument

but scripts/kernel-doc is confused: it always lists varargs as:
... variable arguments
and ignores the @...: line's description, but then prints that
line after the list of function parameters as though it's
not part of the function parameters.

This patch makes kernel-doc print the supplied @... description if it is
present; otherwise a boilerplate "variable arguments" is printed.

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: allow more whitespace in macros

Allow macros that are annotated with kernel-doc to contain whitespace
between the '#' and "define". It's valid and being used, so allow it.

Signed-off-b

kernel-doc: allow more whitespace in macros

Allow macros that are annotated with kernel-doc to contain whitespace
between the '#' and "define". It's valid and being used, so allow it.

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

show more ...

kernel-doc: allow structs whose members are all private

Struct members may be marked as private by using
/* private: */
before them, as noted in Documentation/kernel-doc-nano-HOWTO.txt

Fix kernel-

kernel-doc: allow structs whose members are all private

Struct members may be marked as private by using
/* private: */
before them, as noted in Documentation/kernel-doc-nano-HOWTO.txt

Fix kernel-doc to handle structs whose members are all private;
otherwise invalid XML is generated:

xmlto: input does not validate (status 3)
linux-2.6.27-rc6-git4/Documentation/DocBook/debugobjects.xml:146: element variablelist: validity error : Element variablelist content does not follow the DTD, expecting ((title , titleabbrev?)? , varlistentry+), got ()
Document linux-2.6.27-rc6-git4/Documentation/DocBook/debugobjects.xml does not validate
make[1]: *** [Documentation/DocBook/debugobjects.html] Error 3

Signed-off-by: Randy Dunlap <[email protected]>
Reported-by: Roland McGrath <[email protected]>
Cc: Roland McGrath <[email protected]>
Cc: Christoph Hellwig <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

kernel-doc: skip nested struct/union cleanly

Fix handling of nested structs or unions. The regex to strip (eliminate)
nested structs or unions was limited to only 0 or 1 matches. This can
cause an

kernel-doc: skip nested struct/union cleanly

Fix handling of nested structs or unions. The regex to strip (eliminate)
nested structs or unions was limited to only 0 or 1 matches. This can
cause an uneven number of left/right braces to be stripped, which causes
this:

Warning(linux-2.6.27-rc1-git2//include/net/mac80211.h:336): No description found for parameter '}'

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: handle/strip __init

Handle __init in functions with kernel-doc notation by stripping the
__init away from the output doc. This is already being done for
"__devinit". This patch fixes t

kernel-doc: handle/strip __init

Handle __init in functions with kernel-doc notation by stripping the
__init away from the output doc. This is already being done for
"__devinit". This patch fixes these kernel-doc error/aborts:

Error(linux-next-20080619//drivers/usb/gadget/config.c:132): cannot understand prototype: 'struct usb_descriptor_header **__init usb_copy_descriptors(struct usb_descriptor_header **src) '
Error(linux-next-20080619//drivers/usb/gadget/config.c:182): cannot understand prototype: 'struct usb_endpoint_descriptor *__init usb_find_endpoint( struct usb_descriptor_header **src, struct usb_descriptor_header **copy, struct usb_endpoint_descriptor *match ) '

Signed-off-by: Randy Dunlap <[email protected]>
Cc: David Brownell <[email protected]>
Signed-off-by: Sam Ravnborg <[email protected]>

show more ...

kernel-doc: allow unnamed bit-fields

Allow for unnamed bit-fields and skip them instead of printing an
erroneous warning message for them, such as:

Warning(include/asm-s390/cio.h:103): No descripti

kernel-doc: allow unnamed bit-fields

Allow for unnamed bit-fields and skip them instead of printing an
erroneous warning message for them, such as:

Warning(include/asm-s390/cio.h:103): No description found for parameter 'u32'

which contains:

struct tm_scsw {
u32 :1;

Signed-off-by: Randy Dunlap <[email protected]>
Signed-off-by: Sam Ravnborg <[email protected]>

show more ...

kernel-doc: detect trailing kernel-doc line trash

Print a warning when a kernel-doc comment block ends with text on the same
line as the ending comment characters, e.g.:

* this text is lost. */

S

kernel-doc: detect trailing kernel-doc line trash

Print a warning when a kernel-doc comment block ends with text on the same
line as the ending comment characters, e.g.:

* this text is lost. */

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: detect/prevent duplicate doc section names

I saw this problem recently. With this kernel-doc:

* Note: some important info
*
* Note: other important info

kernel-doc uses the "sectio

kernel-doc: detect/prevent duplicate doc section names

I saw this problem recently. With this kernel-doc:

* Note: some important info
*
* Note: other important info

kernel-doc uses the "section name" (preceding the ':', like "Note") as a hash
key for storing the descriptive text ("blah important info"). It is (was)
possible to have duplicate (colliding) section names, without any kind of
warning or error.

kernel-doc happily used the latter descriptive text for all instances of
printing the <section-name> descriptive text and the former important info
was lost.

One way to "fix" this is to modify the kernel-doc comments, e.g.:

* Note1: foo bar
*
* Note.2: blah zay

For now, kernel-doc will signal an error when it sees colliding section names
like this.

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: set verbose mode via environment

Honor the environment variable "KBUILD_VERBOSE=1" (as set by make V=1) to
enable verbose mode in scripts/kernel-doc. Useful for getting more info and
wa

kernel-doc: set verbose mode via environment

Honor the environment variable "KBUILD_VERBOSE=1" (as set by make V=1) to
enable verbose mode in scripts/kernel-doc. Useful for getting more info and
warnings from kernel-doc.

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

show more ...

kernel-doc: fix function-pointer-parameter parsing

When running "make htmldocs" I'm seeing some non-fatal perl errors caused
by trying to parse the callback function definitions in blk-core.c.

The

kernel-doc: fix function-pointer-parameter parsing

When running "make htmldocs" I'm seeing some non-fatal perl errors caused
by trying to parse the callback function definitions in blk-core.c.

The errors are "Use of uninitialized value in concatenation (.)..."
in combination with:
Warning(linux-2.6.25-rc2/block/blk-core.c:1877): No description found for parameter ''

The function pointers are defined without a * i.e.
int (drv_callback)(struct request *)

The compiler is happy with them, but kernel-doc isn't.

This patch teaches create_parameterlist in kernel-doc to parse this type of
function pointer definition, but is it the right way to fix the problem ?
The problem only seems to occur in blk-core.c.

However with the patch applied, kernel-doc finds the correct parameter
description for the callback in blk_end_request_callback, which is doesn't
normally.

I thought it would be a bit odd to change to code to use the more normal
form of function pointers just to get the documentation to work, so I fixed
kernel-doc instead - even though this is teaching it to understand code
that might go away (The comment for blk_end_request_callback says that it
should not be used and will removed at some point).

Signed-off-by: Richard Kennedy <[email protected]>
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: remove fastcall

fastcall is gone from the tree, no need to adjust the function prototypes
anymore for this.

Signed-off-by: Harvey Harrison <[email protected]>
Acked-by: Randy Du

kernel-doc: remove fastcall

fastcall is gone from the tree, no need to adjust the function prototypes
anymore for this.

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

show more ...

kernel-doc: warn on badly formatted short description

Make kernel-doc warn when a function/struct/union/typedef does not contain
a properly formatted short description, such as:
* scsi_devinfo: set

kernel-doc: warn on badly formatted short description

Make kernel-doc warn when a function/struct/union/typedef does not contain
a properly formatted short description, such as:
* scsi_devinfo: set up the dynamic device list
or
* scsi_devinfo -

This warning is only generated when verbose (-v) mode is used.

Also explain the -v command line option in the -h output.

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: prevent duplicate description: output

Prevent duplicate output of a Description: section when there is a "blank"
("*") line between the initial function name/description line and the
"De

kernel-doc: prevent duplicate description: output

Prevent duplicate output of a Description: section when there is a "blank"
("*") line between the initial function name/description line and the
"Description:" header.

Test case: drivers/scsi/scsi_devinfo.c::scsi_init_devinfo().

Rob Landley hit this while he was producing SCSI kernel-doc.

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: fix for vunmap function prototype

Fix kernel-doc function prototype parsing which was exposed by vunmap() by
allowing more than one '*' before the function name.

Error(linux-2.6.24-mm1/

kernel-doc: fix for vunmap function prototype

Fix kernel-doc function prototype parsing which was exposed by vunmap() by
allowing more than one '*' before the function name.

Error(linux-2.6.24-mm1//mm/vmalloc.c:438): cannot understand prototype: 'struct page **vunmap(const void *addr) '

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: process functions, not DOC:

This flag is necessary for the next patch for docproc to output
only the functions and not DOC: sections when a function list
is requested.

Signed-off-by: Jo

kernel-doc: process functions, not DOC:

This flag is necessary for the next patch for docproc to output
only the functions and not DOC: sections when a function list
is requested.

Signed-off-by: Johannes Berg <[email protected]>
Signed-off-by: Randy Dunlap <[email protected]>
Signed-off-by: Sam Ravnborg <[email protected]>

show more ...

kernel-doc: single DOC: selection

Currently, DOC: sections are always output even if only a single
function is requested, fix this and also make it possible to just
output a single DOC: section by g

kernel-doc: single DOC: selection

Currently, DOC: sections are always output even if only a single
function is requested, fix this and also make it possible to just
output a single DOC: section by giving its title as the function
name to output.

Also fixes docbook XML well-formedness for sections with examples.

Signed-off-by: Johannes Berg <[email protected]>
Signed-off-by: Randy Dunlap <[email protected]>
Signed-off-by: Sam Ravnborg <[email protected]>

show more ...

kernel-doc: init kernel version

The kernel-doc script triggers a perl warning when invoked
without KERNELVERSION in the environment, rather make it use
the string "unknown kernel version" instead.

kernel-doc: init kernel version

The kernel-doc script triggers a perl warning when invoked
without KERNELVERSION in the environment, rather make it use
the string "unknown kernel version" instead.

Signed-off-by: Johannes Berg <[email protected]>
Signed-off-by: Randy Dunlap <[email protected]>
Signed-off-by: Sam Ravnborg <[email protected]>

show more ...

kernel-doc: fix xml output mode

After Randy's patch fixing the HTML output in DOC: sections
(6b5b55f6c404fa730a09a8254eb19f5a038afcc2) the same bug remained in XML
mode, this fixes it.

Signed-off-b

kernel-doc: fix xml output mode

After Randy's patch fixing the HTML output in DOC: sections
(6b5b55f6c404fa730a09a8254eb19f5a038afcc2) the same bug remained in XML
mode, this fixes it.

Signed-off-by: Johannes Berg <[email protected]>
Signed-off-by: Randy Dunlap <[email protected]>
Signed-off-by: Sam Ravnborg <[email protected]>

show more ...