kernel-doc: fix doc blocks and html

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

kernel-doc: fix doc blocks and html

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 &lt;p&gt;, 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 <[email protected]>
Cc: Johannes Berg <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

kernel-doc: fix leading dot in man-mode output

If a parameter description begins with a '.', this indicates a "request"
for "man" mode output (*roff), so it needs special handling.

Problem case is

kernel-doc: fix leading dot in man-mode output

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.

[[email protected]: cleanup]
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: strip C99 comments

Strip C99-style comments from the input stream.
/*...*/ comments are already stripped.
C99 comments confuse the kernel-doc script.

Also update some comments.

Signed-

kernel-doc: strip C99 comments

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 <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

kernel-doc: fix unnamed struct/union warning

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 anon

kernel-doc: fix unnamed struct/union warning

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 <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

kernel-doc: small kernel-doc optimization

Get the kernel version string only once from the environment, thus slightly
speeding up kernel-doc.

Signed-off-by: Borislav Petkov <[email protected]>
Sign

kernel-doc: small kernel-doc optimization

Get the kernel version string only once from the environment, thus slightly
speeding up kernel-doc.

Signed-off-by: Borislav Petkov <[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 ...

kill warnings when building mandocs

This patch shuts warnings of the sort:

make -C /mnt/samsung_200/sam/kernel/trees/21-rc6/build \
KBUILD_SRC=/mnt/samsung_200/sam/kernel/trees/21-rc6 \
KBUILD_EX

kill warnings when building mandocs

This patch shuts warnings of the sort:

make -C /mnt/samsung_200/sam/kernel/trees/21-rc6/build \
KBUILD_SRC=/mnt/samsung_200/sam/kernel/trees/21-rc6 \
KBUILD_EXTMOD="" -f /mnt/samsung_200/sam/kernel/trees/21-rc6/Makefile mandocs
make -f /mnt/samsung_200/sam/kernel/trees/21-rc6/scripts/Makefile.build obj=scripts/basic
make -f /mnt/samsung_200/sam/kernel/trees/21-rc6/scripts/Makefile.build obj=Documentation/DocBook mandocs
SRCTREE=/mnt/samsung_200/sam/kernel/trees/21-rc6/ /mnt/samsung_200/sam/kernel/trees/21-rc6/build/scripts/basic/docproc doc /mnt/samsung_200/sam/kernel/trees/21-rc6/Documentation/DocBook/wanbook.tmpl >Documentation/DocBook/wanbook.xml
if grep -q refentry Documentation/DocBook/wanbook.xml; then xmlto man -m /mnt/samsung_200/sam/kernel/trees/21-rc6/Documentation/DocBook/stylesheet.xsl -o Documentation/DocBook/man Documentation/DocBook/wanbook.xml ; gzip -f Documentation/DocBook/man/*.9; fi
Note: meta version: No productnumber or alternative sppp_close
Note: meta version: No refmiscinfo@class=version sppp_close
Note: Writing sppp_close.9
Note: meta version: No productnumber or alternative sppp_open
Note: meta version: No refmiscinfo@class=version sppp_open

by adding a RefMiscInfo xml tag in the form of the current kernel version
to the function, struct and enum definitions in files included by
kernel-doc when building 'mandocs'. However, the version string appears
truncated on the manpage due to some constraints in the xml DTD for the man
header, I believe, for the troff output is truncated too.

Signed-off-by: Borislav Petkov <[email protected]>
Cc: "Randy.Dunlap" <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

kernel-doc: html mode struct highlights

Johannes Berg reported that struct names are not highlighted
(bold, italic, etc.) in html kernel-doc output. (Also not in
text-mode output, but I don't see t

kernel-doc: html mode struct highlights

Johannes Berg reported that struct names are not highlighted
(bold, italic, etc.) in html kernel-doc output. (Also not in
text-mode output, but I don't see that changing.)

This patch adds the following:
- highlight struct names in html output mode
- highlight environment var. names in html output mode
- indent struct fields in the original struct layout

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

show more ...

kernel-doc: handle arrays with arithmetic expressions as initializers

In a different approach here's a patch that handles the special case of
composite arithmetic expressions in array size initializ

kernel-doc: handle arrays with arithmetic expressions as initializers

In a different approach here's a patch that handles the special case of
composite arithmetic expressions in array size initializers. With it,
prior to pushing the split strings on the @first_arg array, I split the
keywords before the array name as before and then keep the array name along
with the subscript expression as a single whole element which gets pushed
last. In this manner, kernel-doc produces correct output without removing
whitespaces which makes the array subscripts unreadable in the docs.

Signed-off-by: Borislav Petkov <[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 ...

scripts: kernel-doc whitespace cleanup

Whitespace cleanup only: convert some series of spaces to tabs.

Signed-off-by: Randy Dunlap <[email protected]>
Signed-off-by: Andrew Morton <akpm@linu

scripts: kernel-doc whitespace cleanup

Whitespace cleanup only: convert some series of spaces to tabs.

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

show more ...

[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//kerne

[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 <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

[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 outp

[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 <[email protected]>
Acked-by: Johannes Berg <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

[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/ker

[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 <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

[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

[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 <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

[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 nam

[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 <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

[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

[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 <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

[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-s

[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 <[email protected]>
Acked-by: Randy Dunlap <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

[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
curre

[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 <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

[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 ker

[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 <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

[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 descrip

[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 <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

[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

[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 <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

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 <[email protected]>
Acked-by: Alan Cox <

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 <[email protected]>
Acked-by: Alan Cox <[email protected]>
Signed-off-by: Adrian Bunk <[email protected]>

show more ...

[PATCH] kernel-doc: ignore __devinit

Ignore __devinit in function definitions so that kernel-doc won't fail on
them.

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

[PATCH] kernel-doc: ignore __devinit

Ignore __devinit in function definitions so that kernel-doc won't fail on
them.

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

show more ...

[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")

[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 <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

[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 outp

[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 <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

[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

[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 <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...