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>
Current kernel-doc (perl) script generates this warning:
Use of uninitialized value in concatenation (.) or string at scripts/kernel-doc line 1668.
So explicitly check for SRCTREE in the ENV before using it,
and then if it is set, append a '/' to the end of it, otherwise
the SRCTREE + filename can (will) be missing the intermediate '/'.
Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
xmlto uses standared XSLT templates to generate manpages, (x)html pages, and
XML FO files which can be processed with passivetex. This is much faster than
using jadetex for everything. This patch also reduces the number of
kernel-specific scripts that are needed to generate 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>
This fix is needed to create valid XML.
Signed-off-by: Martin Waitz <tali@admingilde.org>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
I have recompiled Linux kernel 2.6.11.5 documentation for me and our
university students again. The documentation could be extended for more
sources which are equipped by structured comments for recent 2.6 kernels. I
have tried to proceed with that task. I have done that more times from 2.6.0
time and it gets boring to do same changes again and again. Linux kernel
compiles after changes for i386 and ARM targets. I have added references to
some more files into kernel-api book, I have added some section names as well.
So please, check that changes do not break something and that categories are
not too much skewed.
I have changed kernel-doc to accept "fastcall" and "asmlinkage" words reserved
by kernel convention. Most of the other changes are modifications in the
comments to make kernel-doc happy, accept some parameters description and do
not bail out on errors. Changed <pid> to @pid in the description, moved some
#ifdef before comments to correct function to comments bindings, etc.
You can see result of the modified documentation build at
http://cmp.felk.cvut.cz/~pisa/linux/lkdb-2.6.11.tar.gz
Some more sources are ready to be included into kernel-doc generated
documentation. Sources has been added into kernel-api for now. Some more
section names added and probably some more chaos introduced as result of quick
cleanup work.
Signed-off-by: Pavel Pisa <pisa@cmp.felk.cvut.cz>
Signed-off-by: Martin Waitz <tali@admingilde.org>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
Initial git repository build. I'm not bothering with the full history,
even though we have it. We can create a separate "historical" git
archive of that later if we want to, and in the meantime it's about
3.2GB when imported into git - space that would just make the early
git days unnecessarily complicated, when we don't have a lot of good
infrastructure for it.
Let it rip!
Randy Dunlap