Allow space(s) between "__attribute__" and "((blah))" so that
kernel-doc does not complain like:
Warning(/tester/linsrc/linux-2.6.20-git15//kernel/timer.c:939): No description found for parameter 'read_persistent_clock(void'
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>
- in man and text mode output, if the function return type is empty (like it
is for macros), don't print the return type and a following space; this
fixes an output malalignment;
- in the function short description, strip leading, trailing, and multiple
embedded spaces (to one space); this makes function name/description output
spacing consistent;
- fix a comment typo;
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 whitespace in pointer-to-function
[accept "(* done)", not just "(*done)"].
Allow tabs (spaces are already allowed) between "#define" and a macro name.
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>
In kernel-doc syntax, be a little flexible: allow whitespace between
a function parameter name and the colon that must follow it, such as:
@pdev : PCI device to unplug
(This allows lots of megaraid kernel-doc to work without tons of
editing.)
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>
The malformed HTML was generated after switch to XSLTPROC
from SGML tools. The reference title
<refentrytitle><phrase id="API-struct-x">struct x</phrase></refentrytitle>
is converted into two recursive <a> tags
<a href="re02.html"><span><a id="API-struct-x"></a>struct x</span></a>
There is more possible solutions for this problem.
One can be found at
http://darkk.livejournal.com/
The proposed solution is based on suggestion provided by Jiri Kosek.
Signed-off-by: Pavel Pisa <pisa@cmp.felk.cvut.cz>
Acked-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 support unnamed (anonymous) structs and unions. There is
one (union) in include/linux/skbuff.h (inside struct sk_buff) that is
currently generating a kernel-doc warning, so this fixes that warning.
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
Be more careful about function pointer args:
look for "(...*" instead of just "(".
This line in include/linux/input.h fools the current kernel-doc script
into deciding that this is a function pointer:
unsigned long ffbit[NBITS(FF_MAX)];
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
- In parameter descriptions, strip all whitespace between the parameter
name (e.g., @len) and its description so that the description is
indented uniformly in text and man page modes. Previously, spaces
or tabs (which are used for cleaner source code viewing) affected
the produced output in a negative way.
Before (man mode):
to Destination address, in user space.
from Source address, in kernel space.
n Number of bytes to copy.
After (man mode):
to Destination address, in user space.
from Source address, in kernel space.
n Number of bytes to copy.
- Fix/clarify a few function description comments.
Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
Drop __inline, __always_inline, and noinline in the produced kernel-doc
output, similar to other pseudo directives.
Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
This is obviously copied from some lines before without proper fixing.
Signed-off-by: Rolf Eike Beer <eike-kernel@sf-tec.de>
Acked-by: Alan Cox <alan@redhat.com>
Signed-off-by: Adrian Bunk <bunk@stusta.de>
Ignore __devinit in function definitions so that kernel-doc won't fail on
them.
Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
Make output of function descriptions in text mode match contents of 'man'
mode by adding Name: plus function-short-description ("purpose") and
changing Function: to Synopsis:.
Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
Add a space between data type and struct field name in man-mode
bitfield struct output so that they don't run together.
For text-mode struct output, print the struct 'purpose' or
short description (as done in man-mode output).
For text-mode enum output, print the enum 'purpose' or
short description (as done in man-mode output).
For text-mode typedef output, print the typedef 'purpose' or
short description (as done in man-mode output).
Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
kernel-doc struct fields should be consistently called "Members", not
"Arguments", so switch man-mode output to use "Members" like all of the
other formats do.
Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
For kernel-doc output modes of text and man, do not use XML escapes for
less-than, greater-than, and ampersand characters. I.e., leave the text
and man output clean and readable.
Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
When the verbose (-v) option is used with scripts/kernel-doc, this option
reports when the kernel-doc format is malformed and apparently contains
function description lines before function parameters. In these cases, the
kernel-doc script will print something like: Warning(filemap.c:335):
contents before sections
I have fixed the problems in mm/filemap.c and added lots of kernel-doc to
that file (posted to the linux-mm mailing list Mon. 2006-June-12).
The real goal (as requested by Andrew Morton) is to allow the short
function description to be more than one line long. This patch is both a
kernel-doc checker and a tool en route to that goal.
Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
Fix indentation.
Quote a brace '{' so that vi won't be fooled by it.
Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
Drop leading space of kernel-doc section contents.
"Section" data (contents) are split from the section header
(e.g., Note: below is a section header:
* Note: list_empty on entry does not return true after this, the entry is
* in an undefined state.
).
Currently the data/contents begins with a space and is left that way, which
causes it to look bad when printed (in text mode; see example below), so
just remove the leading space.
Note:
list_empty on entry does not return true after this, the entry is in an
undefined state.
Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
- Add info that structs, unions, enums, and typedefs are supported.
- Add doc about "private:" and "public:" tags for struct fields.
- Fix some typos.
- Remove some trailing whitespace.
Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
kernel-doc errored out because it could not understand the new __copy_to_user
definition. Now we allow return types with four words.
Signed-off-by: Martin Waitz <tali@admingilde.org>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
Previously kernel-doc silently ignored missing parameter descriptions for
preprocessor macros. Now that all such omissions are fixed up we can warn
about them in kernel-doc to be able to keep it that way.
Signed-off-by: Martin Waitz <tali@admingilde.org>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
Many structures contain both an internal part and one which is part of the API
to other modules. With this patch it is possible to only include these public
members in the kernel documentation.
Signed-off-by: Martin Waitz <tali@admingilde.org>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
