18 Jan, 2016
1 commit
-
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
...
21 Nov, 2015
3 commits
-
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
Signed-off-by: Jonathan Corbet -
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
Signed-off-by: Jonathan Corbet -
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
Signed-off-by: Jonathan Corbet
18 Nov, 2015
1 commit
-
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.htmlRestore 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
Signed-off-by: Jonathan Corbet
06 Nov, 2015
1 commit
-
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 -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
...
12 Oct, 2015
1 commit
-
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
Signed-off-by: Jonathan Corbet
10 Oct, 2015
2 commits
-
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
-
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
14 Sep, 2015
3 commits
-
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:
- @device_for_each_childSorting 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
Signed-off-by: Jonathan Corbet -
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
Signed-off-by: Jonathan Corbet -
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
Signed-off-by: Jonathan Corbet
05 Sep, 2015
1 commit
-
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
Cc: Johannes Berg
Acked-by: Randy Dunlap
Signed-off-by: Andrew Morton
Signed-off-by: Linus Torvalds
24 Aug, 2015
1 commit
-
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
07 Aug, 2015
1 commit
-
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
Cc: Randy Dunlap
Cc: Daniel Vetter
Cc: Laurent Pinchart
Cc: Jonathan Corbet
Cc: Herbert Xu
Cc: Stephan Mueller
Cc: Michal Marek
Cc: linux-kernel@vger.kernel.org
Cc: linux-doc@vger.kernel.org
Cc: intel-gfx
Cc: dri-devel
Signed-off-by: Jonathan Corbet
11 Jul, 2015
2 commits
-
Together with the preceding changes, this allows man pages to be built
reproducibly.Signed-off-by: Ben Hutchings
Signed-off-by: Jonathan Corbet -
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
Signed-off-by: Ben Hutchings
Signed-off-by: Jonathan Corbet
11 Dec, 2014
1 commit
-
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
Cc: Nishanth Menon
Cc: Randy Dunlap
Cc: Michal Marek
Signed-off-by: Andrew Morton
Signed-off-by: Linus Torvalds
27 Aug, 2014
1 commit
-
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
Signed-off-by: Linus Torvalds
13 Jul, 2014
1 commit
-
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.htmlThey are not parsed correctly, generating invalid intermediate
files (xmls) for cases like:
#define BIT_MASK (0xFF << BIT_SHIFT)
where "OxFF <
Signed-off-by: Randy Dunlap
Signed-off-by: Linus Torvalds
16 Nov, 2013
1 commit
-
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
13 Nov, 2013
1 commit
-
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
Cc: Rob Landley
Cc: Randy Dunlap
Signed-off-by: Andrew Morton
Signed-off-by: Linus Torvalds
07 Nov, 2013
1 commit
-
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
Cc: Mark Brown
Signed-off-by: Michal Marek
28 Feb, 2013
1 commit
-
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
Cc: Fengguang Wu
Cc: Johannes Berg
Cc: Randy Dunlap
Cc: Michal Marek
Signed-off-by: Andrew Morton
Signed-off-by: Linus Torvalds
04 Jan, 2013
1 commit
-
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
Signed-off-by: Greg Kroah-Hartman
28 Nov, 2012
1 commit
-
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
Signed-off-by: Rob Landley
Signed-off-by: Jiri Kosina
12 Oct, 2012
1 commit
-
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
06 Oct, 2012
3 commits
-
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
Cc: Randy Dunlap
Cc: Michal Marek
Signed-off-by: Andrew Morton
Signed-off-by: Linus Torvalds -
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
^
/path/Documentation/DocBook/kernel-api.xml:3473: parser error : Opening and ending tag mismatch: para line 3467 and programlisting^
/path/Documentation/DocBook/kernel-api.xml:3678: parser error : Opening and ending tag mismatch: programlisting line 3672 and para
^
/path/Documentation/DocBook/kernel-api.xml:3701: parser error : Opening and ending tag mismatch: para line 3690 and programlisting^
unable to parse
/path/Documentation/DocBook/kernel-api.xmlEssentially, the script attempts to close a with a
closing tag for a 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
Cc: Randy Dunlap
Cc: Michal Marek
Signed-off-by: Andrew Morton
Signed-off-by: Linus Torvalds -
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
Cc: Randy Dunlap
Cc: Michal Marek
Signed-off-by: Andrew Morton
Signed-off-by: Linus Torvalds
31 Aug, 2012
1 commit
-
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
Acked-by: Randy Dunlap
Signed-off-by: Michal Marek
18 Aug, 2012
1 commit
-
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
Signed-off-by: Linus Torvalds
24 Jan, 2012
1 commit
-
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
Cc: Johannes Berg
Signed-off-by: Linus Torvalds
31 Mar, 2011
1 commit
-
Fixes generated by 'codespell' and manually reviewed.
Signed-off-by: Lucas De Marchi
07 Jan, 2011
1 commit
-
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
Signed-off-by: Linus Torvalds
19 Nov, 2010
1 commit
-
scripts/kernel-doc was leaving unescaped '', and '&' in
generated xml output for structs. This causes xml parser errors.
Convert these characters to "<", ">", and "&" 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
Signed-off-by: Linus Torvalds
12 Sep, 2010
2 commits
-
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_confwhen generating the documentation for it.
Signed-off-by: Johannes Berg
Signed-off-by: Randy Dunlap
Signed-off-by: Linus Torvalds -
There are valid attributes that could have upper case letters, but we
still want to remove, like for example
__attribute__((aligned(NETDEV_ALIGN)))
as encountered in the wireless code.Signed-off-by: Johannes Berg
Signed-off-by: Randy Dunlap
Signed-off-by: Linus Torvalds
11 Aug, 2010
1 commit
-
Fix mtd/nand_base.c kernel-doc warnings and typos.
Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'mtd'
Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'ofs'
Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'len'
Warning(drivers/mtd/nand/nand_base.c:893): No description found for parameter 'invert'
Warning(drivers/mtd/nand/nand_base.c:930): No description found for parameter 'mtd'
Warning(drivers/mtd/nand/nand_base.c:930): No description found for parameter 'ofs'
Warning(drivers/mtd/nand/nand_base.c:930): No description found for parameter 'len'
Warning(drivers/mtd/nand/nand_base.c:987): No description found for parameter 'mtd'
Warning(drivers/mtd/nand/nand_base.c:987): No description found for parameter 'ofs'
Warning(drivers/mtd/nand/nand_base.c:987): No description found for parameter 'len'
Warning(drivers/mtd/nand/nand_base.c:2087): No description found for parameter 'len'Signed-off-by: Randy Dunlap
Cc: David Woodhouse
Signed-off-by: Andrew Morton
Signed-off-by: Linus Torvalds
25 Mar, 2010
1 commit
-
Fix a fatal error in scripts/kernel-doc when a function signature uses
__init_or_module (just ignore that string):Error(drivers/base/platform.c:568): cannot understand prototype: 'struct platform_device * __init_or_module platform_create_bundle(struct platform_driver *driver, int (*probe)(struct platform_device *), struct resource *res, unsigned int n_res, const void *data, size_t size) '
Signed-off-by: Randy Dunlap
Signed-off-by: Andrew Morton
Signed-off-by: Linus Torvalds