Link "&foo->bar", "&foo->bar()", "&foo.bar", and "&foo.bar()" to the
struct/union/enum foo definition. The members themselves do not
currently have anchors to link to, but this is better than nothing, and
promotes a universal notation.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Let the user use "&union foo" and "&typedef foo" to reference foo. The
difference to using "union &foo", "typedef &foo", or just "&foo" (which
are valid too) is that "union" and "typedef" become part of the link
text.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
It's possible to use &foo to reference structs, enums, typedefs, etc. in
the Sphinx C domain. Thus do not prefix the links with "struct".
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
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>
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>
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>
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>
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>
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>
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>
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>
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
...
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>
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>
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>
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>
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
...
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>
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>
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>
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>
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>
