Commit Graph

78 Commits

Author SHA1 Message Date
Johannes Berg eda603f6cd docbook: warn on unused doc entries
When you don't use !E or !I but only !F, then it's very easy to miss
including some functions, structs etc.  in documentation.  To help
finding which ones were missed, allow printing out the unused ones as
warnings.

For example, using this on mac80211 yields a lot of warnings like this:

  Warning: didn't use docs for DOC: mac80211 workqueue
  Warning: didn't use docs for ieee80211_max_queues
  Warning: didn't use docs for ieee80211_bss_change
  Warning: didn't use docs for ieee80211_bss_conf

when generating the documentation for it.

Signed-off-by: Johannes Berg <johannes.berg@intel.com>
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2010-09-11 16:49:21 -07:00
Johannes Berg 1f3a66889c kernel-doc: ignore case when stripping attributes
There are valid attributes that could have upper case letters, but we
still want to remove, like for example
	__attribute__((aligned(NETDEV_ALIGN)))
as encountered in the wireless code.

Signed-off-by: Johannes Berg <johannes.berg@intel.com>
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2010-09-11 16:49:21 -07:00
Randy Dunlap b6d676db35 mtd/nand_base: fix kernel-doc warnings & typos
Fix mtd/nand_base.c kernel-doc warnings and typos.

Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'mtd'
Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'ofs'
Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'len'
Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'invert'
Warning(drivers/mtd/nand/nand_base.c:930): No description found for parameter 'mtd'
Warning(drivers/mtd/nand/nand_base.c:930): No description found for parameter 'ofs'
Warning(drivers/mtd/nand/nand_base.c:930): No description found for parameter 'len'
Warning(drivers/mtd/nand/nand_base.c:987): No description found for parameter 'mtd'
Warning(drivers/mtd/nand/nand_base.c:987): No description found for parameter 'ofs'
Warning(drivers/mtd/nand/nand_base.c:987): No description found for parameter 'len'
Warning(drivers/mtd/nand/nand_base.c:2087): No description found for parameter 'len'

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Cc: David Woodhouse <dwmw2@infradead.org>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2010-08-11 08:59:18 -07:00
Randy Dunlap 20072205fc scripts/kernel-doc: fix fatal error on function prototype
Fix a fatal error in scripts/kernel-doc when a function signature uses
__init_or_module (just ignore that string):

Error(drivers/base/platform.c:568): cannot understand prototype: 'struct platform_device * __init_or_module platform_create_bundle(struct platform_driver *driver, int (*probe)(struct platform_device *), struct resource *res, unsigned int n_res, const void *data, size_t size) '

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>
2010-03-24 16:31:20 -07:00
Randy Dunlap ef5da59f12 scripts/kernel-doc: handle struct member __aligned
scripts/kernel-doc erroneously says:

Warning(include/linux/skbuff.h:410): Excess struct/union/enum/typedef member 'cb' description in 'sk_buff'

on this line in struct sk_buff:
	char			cb[48] __aligned(8);

due to treating the last field as the struct member name, so teach
kernel-doc to ignore __aligned(x) in structs.

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>
2010-03-24 16:31:19 -07:00
Randy Dunlap 4c98ecaf35 scripts/kernel-doc: fix empty function description section
scripts/kernel-doc mishandles a function that has a multi-line function
short description and no function parameters.  The observed problem was
from drivers/scsi/scsi_netlink.c:

/**
 * scsi_netlink_init - Called by SCSI subsystem to intialize
 * 	the SCSI transport netlink interface
 *
 **/

kernel-doc treated the " * " line as a Description: section with only a
newline character in the Description contents.  This caused
output_highlight() to complain: "output_highlight got called with no
args?", plus produce a perl call stack backtrace.

The fix is just to ignore Description sections if they only contain "\n".

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>
2010-03-12 15:52:35 -08:00
Ilya Dryomov 1c32fd0c5a kernel-doc: drop the -filelist option, it doesn't work
I also found the -filelist option, but apparently the implementation
is broken, and it was broken from the very first git commit.
For the -filelist option I suggest the removal (I wasn't able to find
any users of it, moreover it's not even listed in the
usage() output, so presumably nobody knows about it).

Signed-off-by: Ilya Dryomov <idryomov@gmail.com>
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2010-02-26 17:23:50 -08:00
Ilya Dryomov a9e7314b79 kernel-doc: track line numbers for each file separately
The problem is that $. keeps track of the current record number (which
is line number by default). But if you pass it multiple files, it does
not wrap at the end of file, and therefore contains the *total* number
of processed lines.
I suppose we can fix line numbering by introducing a simple assignment
$. = 1
before processing every new file.

Signed-off-by: Ilya Dryomov <idryomov@gmail.com>
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2010-02-26 17:23:49 -08:00
Jason Baron 3a9089fd78 tracing: Add DEFINE_EVENT(), DEFINE_SINGLE_EVENT() support to docbook
The introduction of the new 'DECLARE_EVENT_CLASS()' obviates the
need for the 'TRACE_EVENT()' macro in some cases. Thus, docbook
style comments that used to live with 'TRACE_EVENT()' are now
moved to 'DEFINE_EVENT()'. Thus, we need to make the docbook
system understand the new 'DEFINE_EVENT()' macro. In addition
I've tried to futureproof the patch, by also adding support for
'DEFINE_SINGLE_EVENT()', since there has been discussion about
renaming: TRACE_EVENT() -> DEFINE_SINGLE_EVENT().

Without this patch the tracepoint docbook fails to build.

I've verified that this patch correctly builds the tracepoint
docbook which currently covers signals, and irqs.

Changes in v2:
 - properly indent perl 'if' statements

Signed-off-by: Jason Baron <jbaron@redhat.com>
Acked-by: Steven Rostedt <rostedt@goodmis.org>
Acked-by: Randy Dunlap <randy.dunlap@oracle.com>
Cc: William Cohen <wcohen@redhat.com>
Cc: Frederic Weisbecker <fweisbec@gmail.com>
Cc: Mathieu Desnoyers <mathieu.desnoyers@polymtl.ca>
Cc: Masami Hiramatsu <mhiramat@redhat.com>
LKML-Reference: <200912011718.nB1HIn7t011371@int-mx04.intmail.prod.int.phx2.redhat.com>
Signed-off-by: Ingo Molnar <mingo@elte.hu>
2009-12-02 09:57:37 +01:00
Johannes Weiner 6423133bde kernel-doc: allow multi-line declaration purpose descriptions
Allow the short description after symbol name and dash in a kernel-doc
comment to span multiple lines, e.g. like this:

	/**
	 * unmap_mapping_range - unmap the portion of all mmaps in the
	 *	specified address_space corresponding to the specified
	 *	page range in the underlying file.
	 * @mapping: the address space containing mmaps to be unmapped.
	 * ...
	 */

The short description ends with a parameter description, an empty line
or the end of the comment block.

Signed-off-by: Johannes Weiner <hannes@cmpxchg.org>
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2009-09-18 09:48:52 -07:00
Randy Dunlap d960eea974 kernel-doc: move ignoring kmemcheck
Somehow I managed to generate a diff that put these 2 lines
into the wrong function:  should have been in dump_struct()
instead of in dump_enum().

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2009-07-01 11:26:40 -07:00
Randy Dunlap e34e7dbb35 kernel-doc: fix param matching for array params
Fix function actual parameter vs. kernel-doc description matching
so that a warning is not printed when it should not be:

Warning(include/linux/etherdevice.h:199): Excess function parameter 'addr' description in 'is_etherdev_addr'

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
2009-06-20 13:35:01 +02:00
Randy Dunlap b2fd6dbf25 kernel-doc: ignore kmemcheck_bitfield_begin/end
Teach kernel-doc to ignore kmemcheck_bitfield_{begin,end} sugar
so that it won't generate warnings like this:

Warning(include/net/sock.h:297): No description found for parameter 'kmemcheck_bitfield_begin(flags)'
Warning(include/net/sock.h:297): No description found for parameter 'kmemcheck_bitfield_end(flags)'

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
2009-06-20 13:35:00 +02:00
Linus Torvalds 45e3e1935e Merge branch 'master' of git://git.kernel.org/pub/scm/linux/kernel/git/sam/kbuild-next
* 'master' of git://git.kernel.org/pub/scm/linux/kernel/git/sam/kbuild-next: (53 commits)
  .gitignore: ignore *.lzma files
  kbuild: add generic --set-str option to scripts/config
  kbuild: simplify argument loop in scripts/config
  kbuild: handle non-existing options in scripts/config
  kallsyms: generalize text region handling
  kallsyms: support kernel symbols in Blackfin on-chip memory
  documentation: make version fix
  kbuild: fix a compile warning
  gitignore: Add GNU GLOBAL files to top .gitignore
  kbuild: fix delay in setlocalversion on readonly source
  README: fix misleading pointer to the defconf directory
  vmlinux.lds.h update
  kernel-doc: cleanup perl script
  Improve vmlinux.lds.h support for arch specific linker scripts
  kbuild: fix headers_exports with boolean expression
  kbuild/headers_check: refine extern check
  kbuild: fix "Argument list too long" error for "make headers_check",
  ignore *.patch files
  Remove bashisms from scripts
  menu: fix embedded menu presentation
  ...
2009-06-14 14:12:18 -07:00
Randy Dunlap b9d97328e2 kernel-doc: cleanup perl script
Various cleanups of scripts/kernel-doc:
- don't use **/ as an ending kernel-doc block since it's not preferred;
- typos/spellos
- add whitespace around ==, after comma, & around . operator;

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
2009-06-09 23:02:30 +02:00
Ingo Molnar 44347d947f Merge branch 'linus' into tracing/core
Merge reason: tracing/core was on a .30-rc1 base and was missing out on
              on a handful of tracing fixes present in .30-rc5-almost.

Signed-off-by: Ingo Molnar <mingo@elte.hu>
2009-05-07 11:17:34 +02:00
Randy Dunlap 52dc5aec9f kernel-doc: restrict syntax for private: and public:
scripts/kernel-doc can (incorrectly) delete struct members that are
surrounded by /* ...  */ <struct members> /* ...  */ if there is a /*
private: */ comment in there somewhere also.

Fix that by making the "/* private:" only allow whitespace between /* and
"private:", not anything/everything in the world.

This fixes some erroneous kernel-doc warnings that popped up while
processing include/linux/usb/composite.h.

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>
2009-05-02 15:36:10 -07:00
Jason Baron 56afb0f882 kerneldoc, tracing: make kernel-doc understand TRACE_EVENT() macro (take #2)
Add support to kernel-doc for tracepoint comments above TRACE_EVENT()
macro definitions. Paves the way for tracepoint docbook.

[ Impact: extend DocBook infrastructure ]

Signed-off-by: Jason Baron <jbaron@redhat.com>
Acked-by: Randy Dunlap <randy.dunlap@oracle.com>
Cc: akpm@linux-foundation.org
Cc: rostedt@goodmis.org
Cc: fweisbec@gmail.com
Cc: mathieu.desnoyers@polymtl.ca
Cc: wcohen@redhat.com
LKML-Reference: <d80706b6797e277924d2f3ec9af176c6b2951f88.1241107197.git.jbaron@redhat.com>
Signed-off-by: Ingo Molnar <mingo@elte.hu>
2009-05-01 14:03:35 +02:00
Randy Dunlap b4870bc5ee kernel-doc: fix syscall wrapper processing
Fix kernel-doc processing of SYSCALL wrappers.

The SYSCALL wrapper patches played havoc with kernel-doc for
syscalls.  Syscalls that were scanned for DocBook processing
reported warnings like this one, for sys_tgkill:

Warning(kernel/signal.c:2285): No description found for parameter 'tgkill'
Warning(kernel/signal.c:2285): No description found for parameter 'pid_t'
Warning(kernel/signal.c:2285): No description found for parameter 'int'

because the macro parameters all "look like" function parameters,
although they are not:

/**
 *  sys_tgkill - send signal to one specific thread
 *  @tgid: the thread group ID of the thread
 *  @pid: the PID of the thread
 *  @sig: signal to be sent
 *
 *  This syscall also checks the @tgid and returns -ESRCH even if the PID
 *  exists but it's not belonging to the target process anymore. This
 *  method solves the problem of threads exiting and PIDs getting reused.
 */
SYSCALL_DEFINE3(tgkill, pid_t, tgid, pid_t, pid, int, sig)
{
...

This patch special-cases the handling SYSCALL_DEFINE* function
prototypes by expanding them to
	long sys_foobar(type1 arg1, type1 arg2, ...)

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>
2009-02-11 14:25:36 -08:00
Randy Dunlap a1d94aa556 kernel-doc: check for extra kernel-doc notations
Add functionality to check for function parameters or structure (or
union/typedef/enum) field members that are described in kernel-doc but
are not part of the expected (declared) parameters or structure.
These generate warnings that are called "Excess" descriptions.

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
2008-12-19 18:27:19 +01:00
Randy Dunlap ced69090c5 kernel-doc: handle varargs cleanly
The method for listing varargs in kernel-doc notation is:
 * @...: these arguments are printed by the @fmt argument

but scripts/kernel-doc is confused:  it always lists varargs as:
	...	variable arguments
and ignores the @...: line's description, but then prints that
line after the list of function parameters as though it's
not part of the function parameters.

This patch makes kernel-doc print the supplied @...  description if it is
present; otherwise a boilerplate "variable arguments" is printed.

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>
2008-12-01 19:55:25 -08:00
Randy Dunlap 890c78c2d6 kernel-doc: allow more whitespace in macros
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: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2008-10-26 16:32:09 -07:00
Randy Dunlap 39f00c087d kernel-doc: allow structs whose members are all private
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: Randy Dunlap <randy.dunlap@oracle.com>
Reported-by: Roland McGrath <roland@redhat.com>
Cc: Roland McGrath <roland@redhat.com>
Cc: Christoph Hellwig <hch@infradead.org>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2008-09-23 08:09:13 -07:00
Randy Dunlap 32ab8f97dd kernel-doc: skip nested struct/union cleanly
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: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2008-08-05 14:33:49 -07:00
Randy Dunlap 74fc5c653c kernel-doc: handle/strip __init
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: Randy Dunlap <randy.dunlap@oracle.com>
Cc: David Brownell <dbrownell@users.sourceforge.net>
Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
2008-07-25 22:12:38 +02:00
Randy Dunlap 7b97887eab kernel-doc: allow unnamed bit-fields
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: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
2008-05-19 20:12:40 +02:00
Randy Dunlap 46b958eb80 kernel-doc: detect trailing kernel-doc line trash
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: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2008-04-28 08:58:48 -07:00
Randy Dunlap 94dc7ad550 kernel-doc: detect/prevent duplicate doc section names
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: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2008-04-28 08:58:48 -07:00
Randy Dunlap bd0e88e517 kernel-doc: set verbose mode via environment
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: Randy Dunlap <randy.dunlap@oracle.com>
Cc: Sam Ravnborg <sam@ravnborg.org>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2008-03-13 13:11:43 -07:00
Richard Kennedy 00d6296145 kernel-doc: fix function-pointer-parameter parsing
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: Richard Kennedy <richard@rsk.demon.co.uk>
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>
2008-02-23 17:12:16 -08:00
Harvey Harrison 34ff8a52fa kernel-doc: remove fastcall
fastcall is gone from the tree, no need to adjust the function prototypes
anymore for this.

Signed-off-by: Harvey Harrison <harvey.harrison@gmail.com>
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>
2008-02-14 20:58:04 -08:00
Randy Dunlap 77cc23b8c7 kernel-doc: warn on badly formatted short description
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: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2008-02-07 08:42:17 -08:00
Randy Dunlap 792aa2f2cc kernel-doc: prevent duplicate description: output
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: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2008-02-07 08:42:17 -08:00
Randy Dunlap 94b3e03c87 kernel-doc: fix for vunmap function prototype
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: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2008-02-07 08:42:16 -08:00
Johannes Berg 4b44595a7b kernel-doc: process functions, not DOC:
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: Johannes Berg <johannes@sipsolutions.net>
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
2008-01-28 23:14:35 +01:00
Johannes Berg b112e0f73f kernel-doc: single DOC: selection
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: Johannes Berg <johannes@sipsolutions.net>
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
2008-01-28 23:14:35 +01:00
Johannes Berg 1b9bc22d71 kernel-doc: init kernel version
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: Johannes Berg <johannes@sipsolutions.net>
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
2008-01-28 23:14:35 +01:00
Johannes Berg 5c98fc0360 kernel-doc: fix xml output mode
After Randy's patch fixing the HTML output in DOC: sections
(6b5b55f6c4) the same bug remained in XML
mode, this fixes it.

Signed-off-by: Johannes Berg <johannes@sipsolutions.net>
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
2008-01-28 23:14:35 +01:00
Randy Dunlap 6b5b55f6c4 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 <randy.dunlap@oracle.com>
Cc: Johannes Berg <johannes@sipsolutions.net>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2007-10-17 08:43:05 -07:00
Randy Dunlap cdccb316c0 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.

[akpm@linux-foundation.org: cleanup]
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-07-19 10:04:45 -07:00
Randy Dunlap 51f5a0c8f6 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 <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2007-07-19 10:04:45 -07:00
Randy Dunlap 5f8c7c98ae 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 <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2007-07-19 10:04:45 -07:00
Borislav Petkov 0366299bd2 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 <bbpetkov@yahoo.de>
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-05-09 12:30:50 -07:00
Borislav Petkov 53f049fa5f 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 <bbpetkov@yahoo.de>
Cc: "Randy.Dunlap" <rdunlap@xenotime.net>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2007-05-08 11:15:13 -07:00
Randy Dunlap 3eb014a103 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 <randy.dunlap@oracle.com>
Cc: Johannes Berg <johannes@sipsolutions.net>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2007-05-08 11:15:10 -07:00
Borislav Petkov 884f2810b1 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 <bbpetkov@yahoo.de>
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-05-08 11:15:09 -07:00
Randy Dunlap 3c308798a3 scripts: kernel-doc whitespace cleanup
Whitespace cleanup only:  convert some series of spaces to tabs.

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-05-08 11:14:59 -07:00
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