summaryrefslogtreecommitdiffstats
path: root/scripts/kernel-doc
Commit message (Collapse)AuthorAgeFilesLines
* kernel-doc: detect trailing kernel-doc line trashRandy Dunlap2008-04-281-0/+5
| | | | | | | | | | | 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>
* kernel-doc: detect/prevent duplicate doc section namesRandy Dunlap2008-04-281-7/+13
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* kernel-doc: set verbose mode via environmentRandy Dunlap2008-03-131-0/+4
| | | | | | | | | | | 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>
* kernel-doc: fix function-pointer-parameter parsingRichard Kennedy2008-02-231-3/+3
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* kernel-doc: remove fastcallHarvey Harrison2008-02-141-1/+0
| | | | | | | | | | 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>
* kernel-doc: warn on badly formatted short descriptionRandy Dunlap2008-02-071-0/+8
| | | | | | | | | | | | | | | | 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>
* kernel-doc: prevent duplicate description: outputRandy Dunlap2008-02-071-1/+1
| | | | | | | | | | | | | | 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>
* kernel-doc: fix for vunmap function prototypeRandy Dunlap2008-02-071-1/+1
| | | | | | | | | | | 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>
* kernel-doc: process functions, not DOC:Johannes Berg2008-01-281-2/+12
| | | | | | | | | | 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>
* kernel-doc: single DOC: selectionJohannes Berg2008-01-281-20/+43
| | | | | | | | | | | | | 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>
* kernel-doc: init kernel versionJohannes Berg2008-01-281-1/+1
| | | | | | | | | | 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>
* kernel-doc: fix xml output modeJohannes Berg2008-01-281-3/+3
| | | | | | | | | | After Randy's patch fixing the HTML output in DOC: sections (6b5b55f6c404fa730a09a8254eb19f5a038afcc2) 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>
* kernel-doc: fix doc blocks and htmlRandy Dunlap2007-10-171-9/+32
| | | | | | | | | | | | | | | | | | | | | | | | | 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>
* kernel-doc: fix leading dot in man-mode outputRandy Dunlap2007-07-191-1/+5
| | | | | | | | | | | | | | | 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>
* kernel-doc: strip C99 commentsRandy Dunlap2007-07-191-1/+7
| | | | | | | | | | | | 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>
* kernel-doc: fix unnamed struct/union warningRandy Dunlap2007-07-191-4/+10
| | | | | | | | | | | | | 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>
* kernel-doc: small kernel-doc optimizationBorislav Petkov2007-05-091-3/+4
| | | | | | | | | | 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>
* kill warnings when building mandocsBorislav Petkov2007-05-081-0/+12
| | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* kernel-doc: html mode struct highlightsRandy Dunlap2007-05-081-6/+15
| | | | | | | | | | | | | | | | 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>
* kernel-doc: handle arrays with arithmetic expressions as initializersBorislav Petkov2007-05-081-1/+10
| | | | | | | | | | | | | | | 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>
* scripts: kernel-doc whitespace cleanupRandy Dunlap2007-05-081-48/+48
| | | | | | | | 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>
* [PATCH] kernel-doc: allow space after __attribute__Randy Dunlap2007-03-011-1/+1
| | | | | | | | | | | 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>
* [PATCH] kernel-doc: include struct short description in title outputRandy Dunlap2007-02-201-2/+2
| | | | | | | | | | 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>
* [PATCH] fix fatal kernel-doc errorRandy Dunlap2007-02-111-1/+2
| | | | | | | | | | | | | 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>
* [PATCH] kernel-doc: fix some odd spacing issuesRandy Dunlap2007-02-111-4/+20
| | | | | | | | | | | | | | | | - 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 <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
* [PATCH] kernel-doc: allow more whitespaceRandy Dunlap2007-02-111-2/+2
| | | | | | | | | | | 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 <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
* [PATCH] kernel-doc: allow a little whitespaceRandy Dunlap2007-02-111-2/+2
| | | | | | | | | | | | | 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 <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
* [PATCH] DocBook/HTML: correction of recursive A tags in HTML outputPavel Pisa2007-02-111-8/+8
| | | | | | | | | | | | | | | | | | | | | | | 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 <pisa@cmp.felk.cvut.cz> 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>
* [PATCH] kernel-doc: allow unnamed structs/unionsRandy Dunlap2006-12-221-2/+15
| | | | | | | | | | 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 <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
* [PATCH] kernel-doc: stricter function pointer recognitionRandy Dunlap2006-12-071-1/+1
| | | | | | | | | | | | | | 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 <randy.dunlap@oracle.com> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
* [PATCH] kernel-doc: make parameter description indentation uniformRandy Dunlap2006-10-111-5/+7
| | | | | | | | | | | | | | | | | | | | | | | | - 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 <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
* [PATCH] kernel-doc: drop various "inline" qualifiersRandy Dunlap2006-10-111-0/+3
| | | | | | | | | Drop __inline, __always_inline, and noinline in the produced kernel-doc output, similar to other pseudo directives. Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
* Fix copy&waste bug in comment in scripts/kernel-docRolf Eike Beer2006-10-031-2/+2
| | | | | | | | This is obviously copied from some lines before without proper fixing. Signed-off-by: Rolf Eike Beer <eike-kernel@sf-tec.de> Acked-by: Alan Cox <alan@redhat.com> Signed-off-by: Adrian Bunk <bunk@stusta.de>
* [PATCH] kernel-doc: ignore __devinitRandy Dunlap2006-07-311-0/+1
| | | | | | | | | Ignore __devinit in function definitions so that kernel-doc won't fail on them. Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
* [PATCH] kernel-doc: make man/text mode function output sameRandy Dunlap2006-07-011-1/+4
| | | | | | | | | | 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 <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
* [PATCH] kernel-doc: consistent text/man mode outputRandy.Dunlap2006-07-011-3/+5
| | | | | | | | | | | | | | | | | | 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 <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
* [PATCH] kernel-doc: use Members for struct fields consistentlyRandy Dunlap2006-06-251-1/+1
| | | | | | | | | | 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 <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
* [PATCH] kernel-doc: don't use XML escapes in text or man output modeRandy Dunlap2006-06-251-0/+3
| | | | | | | | | | For kernel-doc output modes of text and man, do not use XML escapes for less-than, greater-than, and ampersand characters. I.e., leave the text and man output clean and readable. Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
* [PATCH] kernel-doc: warn on malformed function docs.Randy Dunlap2006-06-251-0/+7
| | | | | | | | | | | | | | | | | | | When the verbose (-v) option is used with scripts/kernel-doc, this option reports when the kernel-doc format is malformed and apparently contains function description lines before function parameters. In these cases, the kernel-doc script will print something like: Warning(filemap.c:335): contents before sections I have fixed the problems in mm/filemap.c and added lots of kernel-doc to that file (posted to the linux-mm mailing list Mon. 2006-June-12). The real goal (as requested by Andrew Morton) is to allow the short function description to be more than one line long. This patch is both a kernel-doc checker and a tool en route to that goal. Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
* [PATCH] kernel-doc: script cleanupsRandy Dunlap2006-06-251-2/+2
| | | | | | | | | Fix indentation. Quote a brace '{' so that vi won't be fooled by it. Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
* [PATCH] kernel-doc: drop leading space in sectionsRandy Dunlap2006-06-251-0/+3
| | | | | | | | | | | | | | | | | | | | | | | Drop leading space of kernel-doc section contents. "Section" data (contents) are split from the section header (e.g., Note: below is a section header: * Note: list_empty on entry does not return true after this, the entry is * in an undefined state. ). Currently the data/contents begins with a space and is left that way, which causes it to look bad when printed (in text mode; see example below), so just remove the leading space. Note: list_empty on entry does not return true after this, the entry is in an undefined state. Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
* [PATCH] kernel-doc: clean up the script (whitespace)Randy Dunlap2006-02-011-34/+34
| | | | | | | | Remove lots of trailing whitespace. Nothing else. Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
* [PATCH] Doc/kernel-doc: add more usage infoRandy Dunlap2006-02-011-3/+3
| | | | | | | | | | | | | | - Add info that structs, unions, enums, and typedefs are supported. - Add doc about "private:" and "public:" tags for struct fields. - Fix some typos. - Remove some trailing whitespace. Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
* [PATCH] DocBook: allow even longer return typesMartin Waitz2006-02-011-2/+4
| | | | | | | | | kernel-doc errored out because it could not understand the new __copy_to_user definition. Now we allow return types with four words. Signed-off-by: Martin Waitz <tali@admingilde.org> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
* [PATCH] DocBook: warn for missing macro parametersMartin Waitz2006-01-101-4/+8
| | | | | | | | | | Previously kernel-doc silently ignored missing parameter descriptions for preprocessor macros. Now that all such omissions are fixed up we can warn about them in kernel-doc to be able to keep it that way. Signed-off-by: Martin Waitz <tali@admingilde.org> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
* [PATCH] DocBook: allow to mark structure members privateMartin Waitz2005-11-131-2/+11
| | | | | | | | | | Many structures contain both an internal part and one which is part of the API to other modules. With this patch it is possible to only include these public members in the kernel documentation. Signed-off-by: Martin Waitz <tali@admingilde.org> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
* [PATCH] scripts/kernel-doc: don't use uninitialized SRCTREERandy Dunlap2005-07-131-1/+7
| | | | | | | | | | | | Current kernel-doc (perl) script generates this warning: Use of uninitialized value in concatenation (.) or string at scripts/kernel-doc line 1668. So explicitly check for SRCTREE in the ENV before using it, and then if it is set, append a '/' to the end of it, otherwise the SRCTREE + filename can (will) be missing the intermediate '/'. Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
* [PATCH] DocBook: Use xmlto to process the DocBook files.Martin Waitz2005-05-011-4/+28
| | | | | | | | | | | xmlto uses standared XSLT templates to generate manpages, (x)html pages, and XML FO files which can be processed with passivetex. This is much faster than using jadetex for everything. This patch also reduces the number of kernel-specific scripts that are needed to generate documentation. Signed-off-by: Martin Waitz <tali@admingilde.org> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
* [PATCH] DocBook: use <informalexample> for examplesRich Walker2005-05-011-4/+9
| | | | | | Signed-off-by: Martin Waitz <tali@admingilde.org> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
* [PATCH] DocBook: fix <void/> xml tagMartin Waitz2005-05-011-1/+1
| | | | | | | | This fix is needed to create valid XML. Signed-off-by: Martin Waitz <tali@admingilde.org> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
OpenPOWER on IntegriCloud