lwn.git/scripts/kernel-doc, branch doc/sphinx

kernel-doc: use rst C domain directives and references for types

2016-03-09T23:20:58+00:00

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 Signed-off-by: Jonathan Corbet

kernel-doc: produce RestructuredText output

2016-03-07T03:27:04+00:00

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

Merge tag 'docs-4.5' of git://git.lwn.net/linux

2016-01-17T19:55:07+00:00

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 ...

kernel-doc: Fix parsing of DECLARE_BITMAP in struct

2015-11-20T23:14:10+00:00

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

kernel-doc: Strip #ifdef/#endif in enums

2015-11-20T23:13:48+00:00

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

kernel-doc: Fix stripping of #define in enums

2015-11-20T23:13:33+00:00

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

kernel-doc: Make it compatible with Perl versions below 5.12 again

2015-11-18T00:20:14+00:00

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 Signed-off-by: Jonathan Corbet

Merge tag 'docs-for-linus' of git://git.lwn.net/linux

2015-11-05T23:59:24+00:00

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 ...

DocBook: Fix kernel-doc to be case-insensitive for private:

2015-10-11T21:37:37+00:00

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

kernel-doc: better format typedef function output

2015-10-10T13:29:06+00:00

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