summaryrefslogtreecommitdiffstats
path: root/scripts/kernel-doc
Commit message (Collapse)AuthorAgeFilesLines
* misc: remove __dev* attributes.Greg Kroah-Hartman2013-01-031-1/+0
| | | | | | | | | | | | | | CONFIG_HOTPLUG is going away as an option. As a result, the __dev* markings need to be removed. This change removes the last of the __dev* markings from the kernel from a variety of different, tiny, places. Based on patches originally written by Bill Pemberton, but redone by me in order to handle some of the coding style issues better, by hand. Cc: Bill Pemberton <wfp5p@virginia.edu> Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
* scripts/kernel-doc: check that non-void fcts describe their return valueYacine Belkadi2012-11-271-0/+34
| | | | | | | | | | | | | | | If a function has a return value, but its kernel-doc comment doesn't contain a "Return" section, then emit the following warning: Warning(file.h:129): No description found for return value of 'fct' Note: This check emits a lot of warnings at the moment, because many functions don't have a 'Return' doc section. So until the number of warnings goes sufficiently down, the check is only performed in verbose mode. Signed-off-by: Yacine Belkadi <yacine.belkadi.1@gmail.com> Signed-off-by: Rob Landley <rob@landley.net> Signed-off-by: Jiri Kosina <jkosina@suse.cz>
* Merge branch 'misc' of ↵Linus Torvalds2012-10-121-7/+266
|\ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | git://git.kernel.org/pub/scm/linux/kernel/git/mmarek/kbuild Pull kbuild misc changes from Michal Marek: "In the non-critical part of kbuild, I have - Some make coccicheck improvements and two new tests - Support for a cleaner html output in scripts/kernel-doc, named html5 (no, it does not play videos, yet) BTW, Randy wants to route further kernel-doc patches through the kbuild tree." * 'misc' of git://git.kernel.org/pub/scm/linux/kernel/git/mmarek/kbuild: Update SmPL/Coccinelle section of MAINTAINERS coccicheck: Add the rep+ctxt mode scripts/coccinelle/tests/odd_ptr_err.cocci: semantic patch for IS_ERR/PTR_ERR inconsistency scripts/tags.sh: Add magic for pci access functions scripts/coccinelle: ptr_ret: Add ternary operator version scripts/kernel-doc: drop maintainer scripts/kernel-doc: added support for html5
| * scripts/kernel-doc: added support for html5Dan Luedtke2012-08-311-7/+266
| | | | | | | | | | | | | | | | | | | | | | New output option html5 writes validating HTML5 and adds CSS classes ready to be selected by third-party stylesheets. HTML ids have been added to block-level elements "article" for direct reference of particular objects via URL. Signed-off-by: Dan Luedtke <mail@danrl.de> Acked-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Michal Marek <mmarek@suse.cz>
* | kernel-doc: don't mangle whitespace in Example sectionDaniel Santos2012-10-061-2/+7
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | A section with the name "Example" (case-insensitive) has a special meaning to kernel-doc. These sections are output using mono-type fonts. However, leading whitespace is stripped, thus robbing a lot of meaning from this, as indented code examples will be mangled. This patch preserves the leading whitespace for "Example" sections. More accurately, it preserves it for all sections, but removes it later if the section isn't an "Example" section. Signed-off-by: Daniel Santos <daniel.santos@pobox.com> Cc: Randy Dunlap <rdunlap@xenotime.net> Cc: Michal Marek <mmarek@suse.cz> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
* | kernel-doc: bugfix - empty line in Example sectionDaniel Santos2012-10-061-1/+10
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | If you have a section named "Example" that contains an empty line, attempting to generate htmldocs give you the error: /path/Documentation/DocBook/kernel-api.xml:3455: parser error : Opening and ending tag mismatch: programlisting line 3449 and para </para><para> ^ /path/Documentation/DocBook/kernel-api.xml:3473: parser error : Opening and ending tag mismatch: para line 3467 and programlisting </programlisting></informalexample> ^ /path/Documentation/DocBook/kernel-api.xml:3678: parser error : Opening and ending tag mismatch: programlisting line 3672 and para </para><para> ^ /path/Documentation/DocBook/kernel-api.xml:3701: parser error : Opening and ending tag mismatch: para line 3690 and programlisting </programlisting></informalexample> ^ unable to parse /path/Documentation/DocBook/kernel-api.xml Essentially, the script attempts to close a <programlisting> with a closing tag for a <para> block. This patch corrects the problem by simply not outputting anything extra when we're dumping pre-formatted text, since the empty line will be rendered correctly anyway. Signed-off-by: Daniel Santos <daniel.santos@pobox.com> Cc: Randy Dunlap <rdunlap@xenotime.net> Cc: Michal Marek <mmarek@suse.cz> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
* | kernel-doc: bugfix - multi-line macrosDaniel Santos2012-10-061-0/+3
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Prior to this patch the following code breaks: /** * multiline_example - this breaks kernel-doc */ #define multiline_example( \ myparam) Producing this error: Error(somefile.h:983): cannot understand prototype: 'multiline_example( \ ' This patch fixes the issue by appending all lines ending in a blackslash (optionally followed by whitespace), removing the backslash and any whitespace after it prior to appending (just like the C pre-processor would). This fixes a break in kerel-doc introduced by the additions to rbtree.h. Signed-off-by: Daniel Santos <daniel.santos@pobox.com> Cc: Randy Dunlap <rdunlap@xenotime.net> Cc: Michal Marek <mmarek@suse.cz> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
* | scripts/kernel-doc: fix fatal script errorRandy Dunlap2012-08-171-0/+1
|/ | | | | | | | | Fix fatal error in scripts/kernel-doc by ignoring the "__weak" attribute: Error(drivers/pci/pci.c:2820): cannot understand prototype: 'char * __weak pcibios_setup(char *str) ' Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
* scripts/kernel-doc: fix fatal error caused by cfg80211.hRandy Dunlap2012-01-231-1/+2
| | | | | | | | | | | | include/net/cfg80211.h uses __must_check in functions that have kernel-doc notation. This was confusing scripts/kernel-doc, so have scripts/kernel-doc ignore "__must_check". Error(include/net/cfg80211.h:2702): cannot understand prototype: 'struct cfg80211_bss * __must_check cfg80211_inform_bss(...) Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Cc: Johannes Berg <johannes@sipsolutions.net> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
* Fix common misspellingsLucas De Marchi2011-03-311-1/+1
| | | | | | Fixes generated by 'codespell' and manually reviewed. Signed-off-by: Lucas De Marchi <lucas.demarchi@profusion.mobi>
* kernel-doc: code reorganizationRandy Dunlap2011-01-061-48/+54
| | | | | | | | | | | | | | Move 'main' code vs. subroutines around so that they are not so intermixed, for better readability/understanding (relative to Perl). It was messy to follow the primary flow of code execution with the code being mixed. Now the code begins with data initialization, followed by all subroutines, then ends with the main code execution. This is almost totally source code movement, with a few changes as needed for forward declarations. Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
* kernel-doc: escape xml for structsRandy Dunlap2010-11-181-3/+9
| | | | | | | | | | | | | | | | scripts/kernel-doc was leaving unescaped '<', '>', and '&' in generated xml output for structs. This causes xml parser errors. Convert these characters to "&lt;", "&gt;", and "&amp;" as needed to prevent errors. Most of the conversion was already done; complete it just before output. Documentation/DocBook/device-drivers.xml:41883: parser error : StartTag: invalid element name #define INPUT_KEYMAP_BY_INDEX (1 << 0) Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
* docbook: warn on unused doc entriesJohannes Berg2010-09-111-2/+50
| | | | | | | | | | | | | | | | | | | | 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>
* kernel-doc: ignore case when stripping attributesJohannes Berg2010-09-111-1/+1
| | | | | | | | | | | 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>
* mtd/nand_base: fix kernel-doc warnings & typosRandy Dunlap2010-08-111-0/+2
| | | | | | | | | | | | | | | | | | | | | 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>
* scripts/kernel-doc: fix fatal error on function prototypeRandy Dunlap2010-03-241-0/+1
| | | | | | | | | | | 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>
* scripts/kernel-doc: handle struct member __alignedRandy Dunlap2010-03-241-0/+2
| | | | | | | | | | | | | | | | 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>
* scripts/kernel-doc: fix empty function description sectionRandy Dunlap2010-03-121-1/+1
| | | | | | | | | | | | | | | | | | | | | | | 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>
* kernel-doc: drop the -filelist option, it doesn't workIlya Dryomov2010-02-261-13/+1
| | | | | | | | | | | | 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>
* kernel-doc: track line numbers for each file separatelyIlya Dryomov2010-02-261-0/+2
| | | | | | | | | | | | | | 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>
* tracing: Add DEFINE_EVENT(), DEFINE_SINGLE_EVENT() support to docbookJason Baron2009-12-021-3/+12
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* kernel-doc: allow multi-line declaration purpose descriptionsJohannes Weiner2009-09-181-5/+16
| | | | | | | | | | | | | | | | | | | | 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>
* kernel-doc: move ignoring kmemcheckRandy Dunlap2009-07-011-2/+2
| | | | | | | | | 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>
* kernel-doc: fix param matching for array paramsRandy Dunlap2009-06-201-0/+17
| | | | | | | | | | 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>
* kernel-doc: ignore kmemcheck_bitfield_begin/endRandy Dunlap2009-06-201-0/+2
| | | | | | | | | | | 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>
* Merge branch 'master' of ↵Linus Torvalds2009-06-141-87/+87
|\ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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 ...
| * kernel-doc: cleanup perl scriptRandy Dunlap2009-06-091-87/+87
| | | | | | | | | | | | | | | | | | | | 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>
* | Merge branch 'linus' into tracing/coreIngo Molnar2009-05-071-3/+4
|\ \ | |/ | | | | | | | | | | 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>
| * kernel-doc: restrict syntax for private: and public:Randy Dunlap2009-05-021-3/+4
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* | kerneldoc, tracing: make kernel-doc understand TRACE_EVENT() macro (take #2)Jason Baron2009-05-011-0/+22
|/ | | | | | | | | | | | | | | | | 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>
* kernel-doc: fix syscall wrapper processingRandy Dunlap2009-02-111-1/+39
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* kernel-doc: check for extra kernel-doc notationsRandy Dunlap2008-12-191-1/+66
| | | | | | | | | | 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>
* kernel-doc: handle varargs cleanlyRandy Dunlap2008-12-011-3/+7
| | | | | | | | | | | | | | | | | | 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>
* kernel-doc: allow more whitespace in macrosRandy Dunlap2008-10-261-3/+3
| | | | | | | | 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>
* kernel-doc: allow structs whose members are all privateRandy Dunlap2008-09-231-0/+4
| | | | | | | | | | | | | | | | | | | | | 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>
* kernel-doc: skip nested struct/union cleanlyRandy Dunlap2008-08-051-1/+1
| | | | | | | | | | | | | 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>
* kernel-doc: handle/strip __initRandy Dunlap2008-07-251-0/+1
| | | | | | | | | | | | | 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>
* kernel-doc: allow unnamed bit-fieldsRandy Dunlap2008-05-191-1/+3
| | | | | | | | | | | | | | | 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>
* 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>
OpenPOWER on IntegriCloud