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: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NLinus 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: NRandy Dunlap <randy.dunlap@oracle.com>
Reported-by: NRoland McGrath <roland@redhat.com>
Cc: Roland McGrath <roland@redhat.com>
Cc: Christoph Hellwig <hch@infradead.org>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus 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: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus 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: NRandy Dunlap <randy.dunlap@oracle.com>
Cc: David Brownell <dbrownell@users.sourceforge.net>
Signed-off-by: NSam 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: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NSam 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: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus 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: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus 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: NRandy Dunlap <randy.dunlap@oracle.com>
Cc: Sam Ravnborg <sam@ravnborg.org>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus 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: NRichard Kennedy <richard@rsk.demon.co.uk>
Signed-off-by: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

fastcall is gone from the tree, no need to adjust the function prototypes
anymore for this.
Signed-off-by: NHarvey Harrison <harvey.harrison@gmail.com>
Acked-by: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus 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: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus 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: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus 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: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus 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: NJohannes Berg <johannes@sipsolutions.net>
Signed-off-by: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NSam 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: NJohannes Berg <johannes@sipsolutions.net>
Signed-off-by: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NSam 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: NJohannes Berg <johannes@sipsolutions.net>
Signed-off-by: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NSam Ravnborg <sam@ravnborg.org>

After Randy's patch fixing the HTML output in DOC: sections
(6b5b55f6) the same bug remained in XML
mode, this fixes it.
Signed-off-by: NJohannes Berg <johannes@sipsolutions.net>
Signed-off-by: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NSam 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 &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: NRandy Dunlap <randy.dunlap@oracle.com>
Cc: Johannes Berg <johannes@sipsolutions.net>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus 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: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus 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: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus 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: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

Get the kernel version string only once from the environment, thus slightly
speeding up kernel-doc.
Signed-off-by: NBorislav Petkov <bbpetkov@yahoo.de>
Signed-off-by: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

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: NBorislav Petkov <bbpetkov@yahoo.de>
Cc: "Randy.Dunlap" <rdunlap@xenotime.net>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

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: NRandy Dunlap <randy.dunlap@oracle.com>
Cc: Johannes Berg <johannes@sipsolutions.net>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

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: NBorislav Petkov <bbpetkov@yahoo.de>
Signed-off-by: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

Whitespace cleanup only:  convert some series of spaces to tabs.
Signed-off-by: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

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: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

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: NRandy Dunlap <randy.dunlap@oracle.com>
Acked-by: NJohannes Berg <johannes@sipsolutions.net>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

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: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NLinus 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: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus 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: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus 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: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus 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: NPavel Pisa <pisa@cmp.felk.cvut.cz>
Acked-by: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus 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: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NAndrew Morton <akpm@osdl.org>
Signed-off-by: NLinus 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: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NAndrew Morton <akpm@osdl.org>
Signed-off-by: NLinus 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: NRandy Dunlap <rdunlap@xenotime.net>
Signed-off-by: NAndrew Morton <akpm@osdl.org>
Signed-off-by: NLinus Torvalds <torvalds@osdl.org>

Drop __inline, __always_inline, and noinline in the produced kernel-doc
output, similar to other pseudo directives.
Signed-off-by: NRandy Dunlap <rdunlap@xenotime.net>
Signed-off-by: NAndrew Morton <akpm@osdl.org>
Signed-off-by: NLinus Torvalds <torvalds@osdl.org>

This is obviously copied from some lines before without proper fixing.
Signed-off-by: NRolf Eike Beer <eike-kernel@sf-tec.de>
Acked-by: NAlan Cox <alan@redhat.com>
Signed-off-by: NAdrian Bunk <bunk@stusta.de>

Ignore __devinit in function definitions so that kernel-doc won't fail on
them.
Signed-off-by: NRandy Dunlap <rdunlap@xenotime.net>
Signed-off-by: NAndrew Morton <akpm@osdl.org>
Signed-off-by: NLinus 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: NRandy Dunlap <rdunlap@xenotime.net>
Signed-off-by: NAndrew Morton <akpm@osdl.org>
Signed-off-by: NLinus Torvalds <torvalds@osdl.org>