litmus-rt.git/scripts/kernel-doc, branch wip-default-clustering

docbook: warn on unused doc entries

2010-09-11T23:49:21+00:00

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 
Signed-off-by: Randy Dunlap 
Signed-off-by: Linus Torvalds

kernel-doc: ignore case when stripping attributes

2010-09-11T23:49:21+00:00

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 
Signed-off-by: Randy Dunlap 
Signed-off-by: Linus Torvalds

mtd/nand_base: fix kernel-doc warnings & typos

2010-08-11T15:59:18+00:00

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 
Cc: David Woodhouse 
Signed-off-by: Andrew Morton 
Signed-off-by: Linus Torvalds

scripts/kernel-doc: fix fatal error on function prototype

2010-03-24T23:31:20+00:00

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

scripts/kernel-doc: handle struct member __aligned

2010-03-24T23:31:19+00:00

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

scripts/kernel-doc: fix empty function description section

2010-03-12T23:52:35+00:00

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

kernel-doc: drop the -filelist option, it doesn't work

2010-02-27T01:23:50+00:00

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 
Signed-off-by: Randy Dunlap 
Signed-off-by: Linus Torvalds

kernel-doc: track line numbers for each file separately

2010-02-27T01:23:49+00:00

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 
Signed-off-by: Randy Dunlap 
Signed-off-by: Linus Torvalds

tracing: Add DEFINE_EVENT(), DEFINE_SINGLE_EVENT() support to docbook

2009-12-02T08:57:37+00:00

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 
Acked-by: Steven Rostedt 
Acked-by: Randy Dunlap 
Cc: William Cohen 
Cc: Frederic Weisbecker 
Cc: Mathieu Desnoyers 
Cc: Masami Hiramatsu 
LKML-Reference: <200912011718.nB1HIn7t011371@int-mx04.intmail.prod.int.phx2.redhat.com>
Signed-off-by: Ingo Molnar

kernel-doc: allow multi-line declaration purpose descriptions

2009-09-18T16:48:52+00:00

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 
Signed-off-by: Randy Dunlap 
Signed-off-by: Linus Torvalds