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 <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
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 <randy.dunlap@oracle.com>
Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
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 <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
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 <randy.dunlap@oracle.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
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 <randy.dunlap@oracle.com>
Reported-by: Roland McGrath <roland@redhat.com>
Cc: Roland McGrath <roland@redhat.com>
Cc: Christoph Hellwig <hch@infradead.org>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
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 <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
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 <randy.dunlap@oracle.com>
Cc: David Brownell <dbrownell@users.sourceforge.net>
Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
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 <randy.dunlap@oracle.com>
Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
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 <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
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 <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
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 <randy.dunlap@oracle.com>
Cc: Sam Ravnborg <sam@ravnborg.org>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
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 <richard@rsk.demon.co.uk>
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
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 <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
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 <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
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 <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
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 <johannes@sipsolutions.net>
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
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 <johannes@sipsolutions.net>
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
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 <johannes@sipsolutions.net>
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
Johannes Berg reports (Thanks!) that &struct names are not highlighted in
html output format when they are inside a DOC: block.
DOC: blocks were not escaped thru xml_escape() like other kernel-doc
comments were. Fixed that.
However, that left a problem with <p> ($blankline_html) being processed
thru xml_escape(), converting it to <p>, which isn't good for the
generated html output (the <p> should remain unchanged), so this patch also
introduces the notion of "local" kernel-doc meta-characters
('\\\\mnemonic:'), which are converted to html just before writing the
stream to its output file.
Please report any problems that you (anyone) see in "highlighting" in any
output mode (text, man, html, xml).
Also update copyright to include me.
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Cc: Johannes Berg <johannes@sipsolutions.net>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
If a parameter description begins with a '.', this indicates a "request"
for "man" mode output (*roff), so it needs special handling.
Problem case is in include/asm-i386/atomic.h for function
atomic_add_unless():
* @u: ...unless v is equal to u.
This parameter description is currently not printed in man mode output.
[akpm@linux-foundation.org: cleanup]
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Strip C99-style comments from the input stream.
/*...*/ comments are already stripped.
C99 comments confuse the kernel-doc script.
Also update some comments.
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Fix kernel-doc warning:
Warning(linux-2.6.22-rc2-git2/include/linux/skbuff.h:316): No description found for parameter '}'
which is caused by nested anonymous structs/unions ending with:
};
};
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
