linux/scripts/kernel-doc, branch v2.6.28

kernel-doc: handle varargs cleanly

2008-12-02T03:55:25Z

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

kernel-doc: allow more whitespace in macros

2008-10-26T23:32:09Z

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

kernel-doc: allow structs whose members are all private

2008-09-23T15:09:13Z

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 Reported-by: Roland McGrath Cc: Roland McGrath Cc: Christoph Hellwig Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds

kernel-doc: skip nested struct/union cleanly

2008-08-05T21:33:49Z

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

kernel-doc: handle/strip __init

2008-07-25T20:12:38Z

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 Cc: David Brownell Signed-off-by: Sam Ravnborg

kernel-doc: allow unnamed bit-fields

2008-05-19T18:12:40Z

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 Signed-off-by: Sam Ravnborg

kernel-doc: detect trailing kernel-doc line trash

2008-04-28T15:58:48Z

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

kernel-doc: detect/prevent duplicate doc section names

2008-04-28T15:58:48Z

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

kernel-doc: set verbose mode via environment

2008-03-13T20:11:43Z

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

kernel-doc: fix function-pointer-parameter parsing

2008-02-24T01:12:16Z

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