Commit Graph

81 Commits

Author SHA1 Message Date
Randy Dunlap 328d24403d [PATCH] kernel-doc: allow space after __attribute__
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>
2007-03-01 14:53:36 -08:00
Randy Dunlap 262d9b0130 [PATCH] kernel-doc: include struct short description in title output
Output of a function or struct in html mode needs to include the short
description from the function/struct name line in the output title line.

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Acked-by: Johannes Berg <johannes@sipsolutions.net>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2007-02-20 17:10:14 -08:00
Randy Dunlap 412ecd7751 [PATCH] fix fatal kernel-doc error
Teach kernel-doc to handle functions that look like the new
pcim_iomap_table().  Fixes this fatal error in scripts/kernel-doc:

  DOCPROC Documentation/DocBook/kernel-api.xml
Error(/tester/linsrc/linux-2.6.20-git6//drivers/pci/pci.c:1351): cannot understand prototype: 'void __iomem * const * pcim_iomap_table(struct pci_dev *pdev) '
make[1]: *** [Documentation/DocBook/kernel-api.xml] Error 1
make: *** [htmldocs] Error 2

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2007-02-11 11:48:20 -08:00
Randy Dunlap a21217daae [PATCH] kernel-doc: fix some odd spacing issues
- 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>
2007-02-11 10:51:32 -08:00
Randy Dunlap 996a07bcb6 [PATCH] kernel-doc: allow more whitespace
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>
2007-02-11 10:51:32 -08:00
Randy Dunlap 891dcd2f7a [PATCH] kernel-doc: allow a little whitespace
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>
2007-02-11 10:51:32 -08:00
Pavel Pisa 5449bc9415 [PATCH] DocBook/HTML: correction of recursive A tags in HTML output
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>
2007-02-11 10:51:30 -08:00
Randy Dunlap 134fe01bfa [PATCH] kernel-doc: allow unnamed structs/unions
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>
2006-12-22 08:55:50 -08:00
Randy Dunlap ea82c74093 [PATCH] kernel-doc: stricter function pointer recognition
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>
2006-12-07 08:39:41 -08:00
Randy Dunlap 272057447f [PATCH] kernel-doc: make parameter description indentation uniform
- 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>
2006-10-11 11:14:24 -07:00
Randy Dunlap 32e794015a [PATCH] kernel-doc: drop various "inline" qualifiers
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>
2006-10-11 11:14:24 -07:00
Rolf Eike Beer a073a8bde4 Fix copy&waste bug in comment in scripts/kernel-doc
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>
2006-10-03 23:13:02 +02:00
Randy Dunlap 0129a057b6 [PATCH] kernel-doc: ignore __devinit
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>
2006-07-31 13:28:40 -07:00
Randy Dunlap f47634b276 [PATCH] kernel-doc: make man/text mode function output same
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>
2006-07-01 09:56:04 -07:00
Randy.Dunlap 1d7e1d4517 [PATCH] kernel-doc: consistent text/man mode output
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>
2006-07-01 09:56:04 -07:00
Randy Dunlap c51d3dac32 [PATCH] kernel-doc: use Members for struct fields consistently
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>
2006-06-25 10:01:23 -07:00
Randy Dunlap ecfb251a95 [PATCH] kernel-doc: don't use XML escapes in text or man output mode
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>
2006-06-25 10:01:23 -07:00
Randy Dunlap 850622dfaf [PATCH] kernel-doc: warn on malformed function docs.
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>
2006-06-25 10:01:20 -07:00
Randy Dunlap 232acbcf53 [PATCH] kernel-doc: script cleanups
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>
2006-06-25 10:01:07 -07:00
Randy Dunlap 05189497d1 [PATCH] kernel-doc: drop leading space in sections
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>
2006-06-25 10:01:07 -07:00
Randy Dunlap 3c3b809e25 [PATCH] kernel-doc: clean up the script (whitespace)
Remove lots of trailing whitespace.  Nothing else.

Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2006-02-01 08:53:27 -08:00
Randy Dunlap d28bee0c0a [PATCH] Doc/kernel-doc: add more usage info
- 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>
2006-02-01 08:53:27 -08:00
Martin Waitz 9598f91f22 [PATCH] DocBook: allow even longer return types
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>
2006-02-01 08:53:27 -08:00
Martin Waitz a6d3fe77da [PATCH] DocBook: warn for missing macro parameters
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>
2006-01-10 08:01:54 -08:00
Martin Waitz aeec46b97a [PATCH] DocBook: allow to mark structure members private
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>
2005-11-13 18:14:21 -08:00
Randy Dunlap 2283a117f6 [PATCH] scripts/kernel-doc: don't use uninitialized SRCTREE
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>
2005-07-13 23:18:36 +00:00
Martin Waitz 8b0c2d989c [PATCH] DocBook: Use xmlto to process the DocBook files.
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>
2005-05-01 08:59:27 -07:00
Rich Walker c73894c1e1 [PATCH] DocBook: use <informalexample> for examples
Signed-off-by: Martin Waitz <tali@admingilde.org>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2005-05-01 08:59:26 -07:00
Martin Waitz 6013d5445f [PATCH] DocBook: fix <void/> xml tag
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>
2005-05-01 08:59:25 -07:00
Pavel Pisa 4dc3b16ba1 [PATCH] DocBook: changes and extensions to the kernel documentation
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>
2005-05-01 08:59:25 -07:00
Linus Torvalds 1da177e4c3 Linux-2.6.12-rc2
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!
2005-04-16 15:20:36 -07:00