summaryrefslogtreecommitdiff
path: root/scripts/kernel-doc
AgeCommit message (Collapse)AuthorFilesLines
2016-05-30kernel-doc/rst: do not output DOC: section titles for requested onesJani Nikula1-1/+3
If the user requests a specific DOC: section by name, do not output its section title. In these cases, the surrounding context already has a heading, and the DOC: section title is only used as an identifier and a heading for clarity in the source file. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-05-30kernel-doc: add names for output selectionJani Nikula1-17/+30
Make the output selection a bit more readable by adding constants for the various types of output selection. While at it, actually call the variable for choosing what to output $output_selection. No functional changes. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-05-30kernel-doc: add names for states and substatesJani Nikula1-43/+48
Make the state machine a bit more readable by adding constants for parser states and inline member documentation parser substates. While at it, rename the "split" documentation to "inline" documentation. No functional changes. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-05-30kernel-doc: support printing exported and non-exported symbolsJani Nikula1-2/+27
Currently we use docproc to figure out which symbols are exported, and then docproc calls kernel-doc on specific functions, to get documentation on exported functions. According to git blame and docproc comments, this is due to historical reasons, as functions and their corresponding EXPORT_SYMBOL* may have been in different files. However for more than ten years the recommendation in CodingStyle has been to place the EXPORT_SYMBOL* immediately after the closing function brace line. Additionally, the kernel-doc comments for functions are generally placed above the function definition in the .c files (i.e. where the EXPORT_SYMBOL* is) rather than above the declaration in the .h files. There are some exceptions to this, but AFAICT none of these are included in DocBook documentation using the "!E" docproc directive. Therefore, assuming the EXPORT_SYMBOL* and kernel-doc are with the function definition, kernel-doc can extract the exported vs. not information by making two passes on the input file. Add support for that via the new -export and -internal parameters. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-05-30kernel-doc/rst: fix use of uninitialized valueJani Nikula1-1/+2
I'm not quite sure why the errors below are happening, but this fixes them. Use of uninitialized value in string ne at ./scripts/kernel-doc line 1819, <IN> line 6494. Use of uninitialized value $_[0] in join or string at ./scripts/kernel-doc line 1759, <IN> line 6494. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-05-14kernel-doc: use rst C domain directives and references for typesJani Nikula1-10/+9
First, the headings for structs, enums and typedefs will be similar to functions. Second, this provides a kind of namespace for cross references. Third, and most importantly, the return and parameter types from .. c:function:: definitions will automagically become cross references to the documented types. Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-05-14kernel-doc: produce RestructuredText outputJonathan Corbet1-0/+233
If given the -rst flag, output will now be in RestructuredText. Various glitches to be worked out yet. In the end I decided not to use RST section headings within the kerneldoc comments. gpu.tmpl already has headings five levels deep; adding more is not going to bring clarity. This is really just Jani Nikula's asciidoc change with the serial numbers filed off. It's a hack job that doubtless needs a lot of cleaning up. Signed-off-by: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-05-14kernel-doc: rewrite usage description, remove duplicated commentsJani Nikula1-46/+37
Instead of having the kernel-doc usage in both comments and in output to the user, merge them all to one here document. While at it, imrove the text and make it pretty. Give shoemaker's children some shoes. Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-01-17Merge tag 'docs-4.5' of git://git.lwn.net/linuxLinus Torvalds1-1/+4
Pull documentation updates from Jon Corbet: "A relatively boring cycle in the docs tree. There's a few kernel-doc fixes and various document tweaks. One patch reaches out of the documentation subtree to fix a comment in init/do_mounts_rd.c. There didn't seem to be anybody more appropriate to take that one, so I accepted it" * tag 'docs-4.5' of git://git.lwn.net/linux: (29 commits) thermal: add description for integral_cutoff unit Documentation: update libhugetlbfs site url Documentation: Explain pci=conf1,conf2 more verbosely DMA-API: fix confusing sentence in Documentation/DMA-API.txt Documentation: translations: update linux cross reference link Documentation: fix typo in CodingStyle init, Documentation: Remove ramdisk_blocksize mentions Documentation-getdelays: Apply a recommendation from "checkpatch.pl" in main() Documentation: HOWTO: update versions from 3.x to 4.x Documentation: remove outdated references from translations Doc: treewide: Fix grammar "a" to "an" Documentation: cpu-hotplug: Fix sysfs mount instructions can-doc: Add hint about getting timestamps Fix CFQ I/O scheduler parameter name in documentation Documentation: arm: remove dead links from Marvell Berlin docs Documentation: HOWTO: update code cross reference link Doc: Docbook/iio: Fix typo in iio.tmpl DocBook: make index.html generation less verbose by default DocBook: Cleanup: remove an unused $(call) line DocBook: Add a help message for DOCBOOKS env var ...
2015-11-21kernel-doc: Fix parsing of DECLARE_BITMAP in structConchúr Navid1-0/+2
Some documented structures in the kernel use DECLARE_BITMAP to create arrays of unsigned longs to store information using the bitmap functions. These have to be replaced with a parsable version for kernel-doc. For example a simple input like /** * struct something - some test * @members: active members */ struct something { DECLARE_BITMAP(members, MAX_MEMBERS); }; resulted in parsing warnings like warning: No description found for parameter 'MAX_MEMBERS)' warning: Excess struct/union/enum/typedef member 'members' description in 'something' Signed-off-by: Conchúr Navid <conchur@web.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2015-11-21kernel-doc: Strip #ifdef/#endif in enumsConchúr Navid1-1/+2
Some enumerations in the kernel headers use #ifdef to reduce their size based on the the configuration. These lines have to be stripped to avoid parsing problems. For example a simple input like /** * enum flags - test flags * @flag1: first flag * @flag2: second flag */ enum flags { flag1 = BIT(0), #ifdef SECOND_FLAG flag2 = BIT(1), #endif }; resulted in parsing warnings like warning: Enum value '#ifdef SECOND_FLAG;flag2 = BIT(1)' not described in enum 'flags' warning: Enum value '#endif;' not described in enum 'flags' Signed-off-by: Conchúr Navid <conchur@web.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2015-11-21kernel-doc: Fix stripping of #define in enumsConchúr Navid1-1/+1
The regex to strip single line #define's in enumerations depends on the fact that the defines are still stored on separate lines. But the surrounding code already removed newlines and replaced them with semicolons. For example a simple input like /** * enum flags - test flags * @flag1: first flag * @flag2: second flag * @flag3: third flag * @flag4: fourth flag */ enum flags { flag1 = BIT(0), flag2 = BIT(1), #define flags_small (flag1 | flag2) flag3 = BIT(2), flag4 = BIT(3), #define flags_big (flag2 | flag3) }; resulted in parsing warnings like warning: Enum value '#define flags_small (flag1 | flag2);flag3 = BIT(2)' not described in enum 'flags' warning: Enum value '#define flags_big (flag2 | flag3);' not described in enum 'flags' Signed-off-by: Conchúr Navid <conchur@web.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2015-11-18kernel-doc: Make it compatible with Perl versions below 5.12 againMauro Carvalho Chehab1-1/+1
Changeset 4d73270192ec('scripts/kernel-doc: Replacing highlights hash by an array') broke compatibility of the kernel-doc script with older versions of perl by using "keys ARRAY" syntax with is available only on Perl 5.12 or newer, according with: http://perldoc.perl.org/functions/keys.html Restore backward compatibility by replacing "foreach my $k (keys ARRAY)" by a C-like variant: "for (my $k = 0; $k < !ARRAY; $k++)" Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2015-11-06Merge tag 'docs-for-linus' of git://git.lwn.net/linuxLinus Torvalds1-51/+68
Pull documentation update from Jon Corbet: "There is a nice new document from Neil on how pathname lookups work and some new CAN driver documentation. Beyond that, we have kernel-doc fixes, a bit more work to support reproducible builds, and the usual collection of small fixes" * tag 'docs-for-linus' of git://git.lwn.net/linux: (34 commits) Documentation: add new description of path-name lookup. Documentation/vm/slub.txt: document slabinfo-gnuplot.sh Doc: ABI/stable: Fix typo in ABI/stable doc: Clarify that nmi_watchdog param is for hardlockups Typo correction for description in gpio document. DocBook: Fix kernel-doc to be case-insensitive for private: kernel-docs.txt: update kernelnewbies reference Doc:kvm: Fix typo in Doc/virtual/kvm Documentation/Changes: Add bc in "Current Minimal Requirements" section Documentation/email-clients.txt: remove trailing whitespace DocBook: Use a fixed encoding for output MAINTAINERS: The docs tree has moved Docs/kernel-parameters: Add earlycon devicetree usage SubmittingPatches: make Subject examples match the de facto standard Documentation: gpio: mention that <function>-gpio has been deprecated Documentation: cgroups: just fix a few typos Documentation: Update kselftest.txt Documentation: DMA API: Be more explicit that nents is always the same Documentation: Update the default value of crashkernel low zram: update documentation ...
2015-10-12DocBook: Fix kernel-doc to be case-insensitive for private:Mauro Carvalho Chehab1-2/+2
On some places, people could use Private: to tag the private fields of an struct. So, be case-insensitive when parsing "private:" meta-tag. Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2015-10-10kernel-doc: better format typedef function outputMauro Carvalho Chehab1-9/+22
A typedef function looks more likely a function and not a normal typedef. Change the code to use the output_function_*, in order to properly parse the function prototype parameters. Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
2015-10-10kernel-doc: Add a parser for function typedefsMauro Carvalho Chehab1-0/+12
The current typedef parser only works for non-function typedefs. As we need to also document some function typedefs, add a parser for it. Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
2015-09-13scripts/kernel-doc: Replacing highlights hash by an arrayDanilo Cesar Lemes de Paula1-44/+60
The "highlight" code is very sensible to the order of the hash keys, but the order of the keys cannot be predicted. It generates faulty DocBook entries like: - @<function>device_for_each_child</function> Sorting the result is not enough some times (as it's deterministic but we can't control it). We should use an array for that job, so we can guarantee that the order of the regex execution on dohighlight is correct. [jc: I think this is kind of papering around the real problem, that people are saying @function() when "function" is not a parameter. But this makes things better than they were before, so...] Signed-off-by: Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2015-09-13Documentation: Avoid creating man pages in source treeBen Hutchings1-4/+5
Currently kernel-doc generates a dummy DocBook file when asked to convert a C source file with no structured comments. For an out-of-tree build (objtree != srctree), the title of the output file is the absolute path name of the C source file, which later results in a manual page being created alongside the C source file. Change the title to be a relative path. Signed-off-by: Ben Hutchings <ben@decadent.org.uk> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2015-09-13scripts/kernel-doc: Processing -nofunc for functions onlyDanilo Cesar Lemes de Paula1-1/+1
Docproc processes the EXPORT_SYMBOL(f1) macro and uses -nofunc f1 to avoid duplicated documentation in the next call. It works for most of the cases, but there are some specific situations where a struct has the same name of an already-exported function. Current kernel-doc behavior ignores those structs and does not add them to the final documentation. This patch fixes it. This is unusual, the only case I've found is the drm_modeset_lock (function and struct) defined in drm_modeset_lock.h and drm_modeset_lock.c. Considering this, it should only affect the DRM documentation by including struct drm_modeset_lock to the final Docbook. Signed-off-by: Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2015-09-05kerneldoc: Convert error messages to GNU error message formatBart Van Assche1-19/+19
Editors like emacs and vi recognize a number of error message formats. The format used by the kerneldoc tool is not recognized by emacs. Change the kerneldoc error message format to the GNU style such that the emacs prev-error and next-error commands can be used to navigate through kerneldoc error messages. For more information about the GNU error message format, see also https://www.gnu.org/prep/standards/html_node/Errors.html. This patch has been generated via the following sed command: sed -i.orig 's/Error(\${file}:\$.):/\${file}:\$.: error:/g;s/Warning(\${file}:\$.):/\${file}:\$.: warning:/g;s/Warning(\${file}):/\${file}:1: warning:/g;s/Info(\${file}:\$.):/\${file}:\$.: info:/g' scripts/kernel-doc Signed-off-by: Bart Van Assche <bart.vanassche@sandisk.com> Cc: Johannes Berg <johannes.berg@intel.com> Acked-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2015-08-23kernel-doc: ignore unneeded attribute informationJonathan Corbet1-0/+2
The kernel-doc script gets confused by __attribute__(()) strings in structures, so just clean the out. Also ignore the CRYPTO_MINALIGN_ATTR macro used in the crypto subsystem. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2015-08-06scripts/kernel-doc Allow struct arguments documentation in struct bodyDanilo Cesar Lemes de Paula1-2/+75
Describing arguments at top of a struct definition works fine for small/medium size structs, but it definitely doesn't work well for struct with a huge list of elements. Keeping the arguments list inside the struct body makes it easier to maintain the documentation. ie: /** * struct my_struct - short description * @a: first member * @b: second member * * Longer description */ struct my_struct { int a; int b; /** * @c: This is longer description of C * * You can use paragraphs to describe arguments * using this method. */ int c; }; This patch allows the use of this kind of syntax. Only one argument per comment and user can use how many paragraphs he needs. It should start with /**, which is already being used by kernel-doc. If those comment doesn't follow those rules, it will be ignored. Signed-off-by: Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> Cc: Randy Dunlap <rdunlap@infradead.org> Cc: Daniel Vetter <daniel.vetter@ffwll.ch> Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: Herbert Xu <herbert@gondor.apana.org.au> Cc: Stephan Mueller <smueller@chronox.de> Cc: Michal Marek <mmarek@suse.cz> Cc: linux-kernel@vger.kernel.org Cc: linux-doc@vger.kernel.org Cc: intel-gfx <intel-gfx@lists.freedesktop.org> Cc: dri-devel <dri-devel@lists.freedesktop.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2015-07-10scripts/kernel-doc: Use $KBUILD_BUILD_TIMESTAMP as man page dateBen Hutchings1-3/+12
Together with the preceding changes, this allows man pages to be built reproducibly. Signed-off-by: Ben Hutchings <ben@decadent.org.uk> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2015-07-10scripts/kernel-doc: parse kernel-doc deterministicallyJérémy Bobbio1-1/+1
Regular expressions for highlights in kernel-doc are stored in a Perl hash. These hashes are ordered differently for each Perl run. This will prevent kernel-doc to behave deterministically when parsing “@foo()” as in some runs it will be interpreted as a parameter and in the others it will be interpreted as a function. We now sort the %highlights hash to get the same behavior on every run. Signed-off-by: Jérémy Bobbio <lunar@debian.org> Signed-off-by: Ben Hutchings <ben@decadent.org.uk> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2014-12-11scripts/kernel-doc: don't eat struct members with __alignedJohannes Berg1-1/+1
The change from \d+ to .+ inside __aligned() means that the following structure: struct test { u8 a __aligned(2); u8 b __aligned(2); }; essentially gets modified to struct test { u8 a; }; for purposes of kernel-doc, thus dropping a struct member, which in turns causes warnings and invalid kernel-doc generation. Fix this by replacing the catch-all (".") with anything that's not a semicolon ("[^;]"). Fixes: 9dc30918b23f ("scripts/kernel-doc: handle struct member __aligned without numbers") Signed-off-by: Johannes Berg <johannes.berg@intel.com> Cc: Nishanth Menon <nm@ti.com> Cc: Randy Dunlap <rdunlap@infradead.org> Cc: Michal Marek <mmarek@suse.cz> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2014-08-27scripts/kernel-doc: recognize __meminitRandy Dunlap1-0/+1
Fix scripts/kernel-doc to recognize __meminit in a function prototype and to strip it, as done with many other attributes. Fixes this warning: Warning(..//mm/page_alloc.c:2973): cannot understand function prototype: 'void * __meminit alloc_pages_exact_nid(int nid, size_t size, gfp_t gfp_mask) ' Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2014-07-12scripts/kernel-doc: handle object-like macrosHoria Geanta1-3/+12
Object-like macros are different than function-like macros: https://gcc.gnu.org/onlinedocs/cpp/Object-like-Macros.html https://gcc.gnu.org/onlinedocs/cpp/Function-like-Macros.html They are not parsed correctly, generating invalid intermediate files (xmls) for cases like: #define BIT_MASK (0xFF << BIT_SHIFT) where "OxFF <<" is considered to be parameter type. When parsing, we can differentiate beween these two types of macros by checking whether there is at least one whitespace b/w "#define" and first opening parenthesis. Signed-off-by: Horia Geanta <horia.geanta@freescale.com> Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2013-11-16Merge branch 'misc' of ↵Linus Torvalds1-2/+1
git://git.kernel.org/pub/scm/linux/kernel/git/mmarek/kbuild Pull misc kbuild changes from Michal Marek: - make tags fixes again - scripts/show_delta fix for newer python - scripts/kernel-doc does not fail on unknown function prototype - one less coccinelle check this time * 'misc' of git://git.kernel.org/pub/scm/linux/kernel/git/mmarek/kbuild: scripts/tags.sh: remove obsolete __devinit[const|data] scripts/kernel-doc: make unknown function prototype a Warning instead of an Error show_delta: Update script to support python versions 2.5 through 3.3 scripts/coccinelle/api: remove devm_request_and_ioremap.cocci scripts/tags.sh: Increase identifier list
2013-11-13kernel-doc: improve "no structured comments found" errorJohannes Berg1-0/+6
When using '!Ffile function' in a docbook template, and the function no longer exists, you get a "no structured comments found" error from the kernel-doc processing script. It's useful to know which functions it was looking for, so print them out in this case. Also do the same for '!Pfile doc-section' The same error also happens when using '!Efile' when some exported functions aren't documented (in the same file.) There's a very large number of such functions though, so don't print the message in this case -- right now it would give ~850 messages. Signed-off-by: Johannes Berg <johannes.berg@intel.com> Cc: Rob Landley <rob@landley.net> Cc: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2013-11-07scripts/kernel-doc: make unknown function prototype a Warning instead of an ↵Randy Dunlap1-2/+1
Error When scripts/kernel-doc cannot understand a function prototype, it had been generating a fatal error and stopping immediately. Make this a Warning instead of an Error and keep going. Note that this can happen if the kernel-doc notation that is being parsed is not actually a function prototype; maybe it's a struct or something else, so I added "function" to the warning message to try to make it clearer that scripts/kernel-doc is looking for a function prototype here. Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Cc: Mark Brown <broonie@kernel.org> Signed-off-by: Michal Marek <mmarek@suse.cz>
2013-02-28scripts/kernel-doc: handle struct member __aligned without numbersNishanth Menon1-1/+1
Commit ef5da59f1260 ("scripts/kernel-doc: handle struct member __aligned") permits "char something [123] __aligned(8);". However, by using \d we constraint ourselves with integers. This is not always the case. In fact, it might be better to do char something[123] __aligned(sizeof(u16)); For example, With wireless_dev defining: u8 address[ETH_ALEN] __aligned(sizeof(u16)); With \d, scripts/kernel-doc erroneously says: Warning(include/net/cfg80211.h:2618): Excess struct/union/enum/typedef member 'address' description in 'wireless_dev' This is because the regex __aligned\s*\(\d+\) fails match at \d as sizeof is used. So replace \d with . to indicate "something" in kernel-doc to ignore __aligned(SOMETHING) in structs. With this change, we can use integers OR sizeof() or macros as we please. Signed-off-by: Nishanth Menon <nm@ti.com> Cc: Fengguang Wu <fengguang.wu@intel.com> Cc: Johannes Berg <johannes.berg@intel.com> Cc: Randy Dunlap <rdunlap@infradead.org> Cc: Michal Marek <mmarek@suse.cz> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2013-01-04misc: remove __dev* attributes.Greg Kroah-Hartman1-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>
2012-11-28scripts/kernel-doc: check that non-void fcts describe their return valueYacine Belkadi1-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>
2012-10-12Merge branch 'misc' of ↵Linus Torvalds1-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
2012-10-05kernel-doc: don't mangle whitespace in Example sectionDaniel Santos1-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>
2012-10-05kernel-doc: bugfix - empty line in Example sectionDaniel Santos1-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>
2012-10-05kernel-doc: bugfix - multi-line macrosDaniel Santos1-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>
2012-08-31scripts/kernel-doc: added support for html5Dan Luedtke1-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>
2012-08-17scripts/kernel-doc: fix fatal script errorRandy Dunlap1-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>
2012-01-23scripts/kernel-doc: fix fatal error caused by cfg80211.hRandy Dunlap1-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>
2011-03-31Fix common misspellingsLucas De Marchi1-1/+1
Fixes generated by 'codespell' and manually reviewed. Signed-off-by: Lucas De Marchi <lucas.demarchi@profusion.mobi>
2011-01-06kernel-doc: code reorganizationRandy Dunlap1-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>
2010-11-19kernel-doc: escape xml for structsRandy Dunlap1-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>
2010-09-12docbook: warn on unused doc entriesJohannes Berg1-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>
2010-09-12kernel-doc: ignore case when stripping attributesJohannes Berg1-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>
2010-08-11mtd/nand_base: fix kernel-doc warnings & typosRandy Dunlap1-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>
2010-03-25scripts/kernel-doc: fix fatal error on function prototypeRandy Dunlap1-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>
2010-03-25scripts/kernel-doc: handle struct member __alignedRandy Dunlap1-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>
2010-03-13scripts/kernel-doc: fix empty function description sectionRandy Dunlap1-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>