documentation mechanism based on the Sphinx system. The objectives here
are to make it easier to create better-integrated (and more attractive)
documents while (eventually) dumping our one-of-a-kind, cobbled-together
system for something that is widely used and maintained by others. There's
a fair amount of information what's being done, why, and how to use it in:
https://lwn.net/Articles/692704/https://lwn.net/Articles/692705/
Closer to home, Documentation/kernel-documentation.rst describes how it
works.
For now, the new system exists alongside the old one; you should soon see
the GPU documentation converted over in the DRM pull and some significant
media conversion work as well. Once all the docs have been moved over and
we're convinced that the rough edges (of which are are a few) have been
smoothed over, the DocBook-based stuff should go away.
Primary credit is to Jani Nikula for doing the heavy lifting to make this
stuff actually work; there has also been notable effort from Markus Heiser,
Daniel Vetter, and Mauro Carvalho Chehab.
Expect a couple of conflicts on the new index.rst file over the course of
the merge window; they are trivially resolvable. That file may be a bit of
a conflict magnet in the short term, but I don't expect that situation to
last for any real length of time.
Beyond that, of course, we have the usual collection of tweaks, updates,
and typo fixes.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1
iQIcBAABAgAGBQJXlT8bAAoJEI3ONVYwIuV6IF0QAM7qpEgAveXgwzGr18ReftjB
ryyPXdLNX8R7fQkUAu85Znlw93k4+7QxHseBgZ1I3t9IhjvzemidOKfj96SJ0DVE
zco5FUTO1TPfO2uG8asNzlXSrwktrEZoFTraRIYpCjAAimg/UEQAM4xgNOJfmW39
8eLg6dhnzqnfCH6M+Q7AZPLmqNSOfA2qNFqHNs7VCbwjLQC0l4yw4PHOsdX0QhCL
NtlukHOhB4CwaELDl6lZOQgnz79e4pDljFd/wA/vVpdq7ev8NnOgVVt93M2fUvLX
Bdfzo2OtZg7LJnWtpQl2LJq2MJJdOmgIw+ls6cB5gvxV3+CCIndE/6IIbimC/lZi
DiaaqVU/EV3AemBDbqErO4k3ZvMT2ZTaSx1OQoLpIwNAsAkEOkb+t2hcwrTqhxg1
kEIXEEboXwStBtH3iar2YiGHQWUhia4mxfv5n4Dvamaca4tGWXHWxSRjbRcaJ1ef
v1kt6ymjwr2sd9116EUxngfYONwlrhk5F87D/dC2eQzEyS0z7+F8wWb/h2gsAaU1
6oVCoQjTe2KAc/7dHINMSIjg2TfVfHS5XIhWu5z6wyxRb8ey9QuKLQYlOTV/L3Ms
aR4O6qvDIsIbOvEd+hHSIbeG7JOPd0LdSI4tdo4d9kquW2OJ6TmmOr/ihbJt430v
s/Qxqwgme/8DJd3KcV6j
=4fDK
-----END PGP SIGNATURE-----
Merge tag 'docs-for-linus' of git://git.lwn.net/linux
Pull documentation updates from Jonathan Corbet:
"Some big changes this month, headlined by the addition of a new
formatted documentation mechanism based on the Sphinx system.
The objectives here are to make it easier to create better-integrated
(and more attractive) documents while (eventually) dumping our
one-of-a-kind, cobbled-together system for something that is widely
used and maintained by others. There's a fair amount of information
what's being done, why, and how to use it in:
https://lwn.net/Articles/692704/https://lwn.net/Articles/692705/
Closer to home, Documentation/kernel-documentation.rst describes how
it works.
For now, the new system exists alongside the old one; you should soon
see the GPU documentation converted over in the DRM pull and some
significant media conversion work as well. Once all the docs have
been moved over and we're convinced that the rough edges (of which are
are a few) have been smoothed over, the DocBook-based stuff should go
away.
Primary credit is to Jani Nikula for doing the heavy lifting to make
this stuff actually work; there has also been notable effort from
Markus Heiser, Daniel Vetter, and Mauro Carvalho Chehab.
Expect a couple of conflicts on the new index.rst file over the course
of the merge window; they are trivially resolvable. That file may be
a bit of a conflict magnet in the short term, but I don't expect that
situation to last for any real length of time.
Beyond that, of course, we have the usual collection of tweaks,
updates, and typo fixes"
* tag 'docs-for-linus' of git://git.lwn.net/linux: (77 commits)
doc-rst: kernel-doc: fix handling of address_space tags
Revert "doc/sphinx: Enable keep_warnings"
doc-rst: kernel-doc directive, fix state machine reporter
docs: deprecate kernel-doc-nano-HOWTO.txt
doc/sphinx: Enable keep_warnings
Documentation: add watermark_scale_factor to the list of vm systcl file
kernel-doc: Fix up warning output
docs: Get rid of some kernel-documentation warnings
doc-rst: add an option to ignore DocBooks when generating docs
workqueue: Fix a typo in workqueue.txt
Doc: ocfs: Fix typo in filesystems/ocfs2-online-filecheck.txt
Documentation/sphinx: skip build if user requested specific DOCBOOKS
Documentation: add cleanmediadocs to the documentation targets
Add .pyc files to .gitignore
Doc: PM: Fix a typo in intel_powerclamp.txt
doc-rst: flat-table directive - initial implementation
Documentation: add meta-documentation for Sphinx and kernel-doc
Documentation: tiny typo fix in usb/gadget_multi.txt
Documentation: fix wrong value in md.txt
bcache: documentation formatting, edited for clarity, stripe alignment notes
...
Pull x86 build updates from Ingo Molnar:
"A build system fix and a cleanup"
* 'x86-build-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip:
kbuild: Remove stale asm-generic wrappers
kbuild, x86: Track generated headers with generated-y
Here is the big Staging and IIO driver update for 4.8-rc1.
We ended up adding more code than removing, again, but it's not all that
bad. Lots of cleanups all over the staging tree, and new IIO drivers,
full details in the shortlog.
All of these have been in linux-next for a while with no reported issues.
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2
iFYEABECABYFAleVPQQPHGdyZWdAa3JvYWguY29tAAoJEDFH1A3bLfsplRgAniG6
jfPnvlHhl70T5HsGJzrc7VS9AKCBQ5x0gzTNxo2nnGfPmR8CVEH7Bg==
=0/6X
-----END PGP SIGNATURE-----
Merge tag 'staging-4.8-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging
Pull staging and IIO driver updates from Greg KH:
"Here is the big Staging and IIO driver update for 4.8-rc1.
We ended up adding more code than removing, again, but it's not all
that bad. Lots of cleanups all over the staging tree, and new IIO
drivers, full details in the shortlog.
All of these have been in linux-next for a while with no reported
issues"
* tag 'staging-4.8-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging: (417 commits)
drivers:iio:accel:mma8452: removed unwanted return statements
drivers:iio:accel:mma8452: added cleanup provision in case of failure.
iio: Add iio.git tree to MAINTAINERS
iio:st_pressure: clean useless static channel initializers
iio:st_pressure:lps22hb: temperature support
iio:st_pressure:lps22hb: open drain support
iio:st_pressure: temperature triggered buffering
iio:st_pressure: document sampling gains
iio:st_pressure: align storagebits on power of 2
iio:st_sensors: align on storagebits boundaries
staging:iio:lis3l02dq drop separate driver
iio: accel: st_accel: Add lis3l02dq support
iio: adc: add missing of_node references to iio_dev
iio: adc: ti-ads1015: add indio_dev->dev.of_node reference
iio: potentiometer: Fix typo in Kconfig
iio: potentiometer: mcp4531: Add device tree binding
iio: potentiometer: mcp4531: Add device tree binding documentation
iio: potentiometer: mcp4531: Add support for MCP454x, MCP456x, MCP464x and MCP466x
iio:imu:mpu6050: icm20608 initial support
iio: adc: max1363: Add device tree binding
...
The RST cpp:function handler is very pedantic: it doesn't allow any
macros like __user on it:
Documentation/media/kapi/dtv-core.rst:28: WARNING: Error when parsing function declaration.
If the function has no return type:
Error in declarator or parameters and qualifiers
Invalid definition: Expecting "(" in parameters_and_qualifiers. [error at 8]
ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
--------^
If the function has a return type:
Error in declarator or parameters and qualifiers
If pointer to member declarator:
Invalid definition: Expected '::' in pointer to member (function). [error at 37]
ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
-------------------------------------^
If declarator-id:
Invalid definition: Expecting "," or ")" in parameters_and_qualifiers, got "*". [error at 102]
ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
------------------------------------------------------------------------------------------------------^
So, we have to remove it from the function prototype.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
While trying to make gpu docs warning free I stumbled over one output
which wasn't following proper compiler error output standards. Fix it
up for more quickfix awesomeness.
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Jani Nikula <jani.nikula@intel.com>
Cc: linux-doc@vger.kernel.org
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This reverts commit e127a73d41 ("scripts/gdb: add a Radix Tree
Parser")
The python implementation of radix-tree was merged at the same time as
the radix-tree system was heavily reworked from commit e9256efcc8
("radix-tree: introduce radix_tree_empty") to 3bcadd6fa6 ("radix-tree:
free up the bottom bit of exceptional entries for reuse") and no longer
functions, but also prevents other gdb scripts from loading.
This functionality has not yet hit a release, so simply remove it for
now
Link: http://lkml.kernel.org/r/1467127337-11135-6-git-send-email-kieran@bingham.xyz
Signed-off-by: Kieran Bingham <kieran@bingham.xyz>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Python doesn't do automatic expansion of paths. In case one passes path
of the from ~/foo/bar the gdb scripts won't automatically expand that
and as a result the symbols files won't be loaded.
Fix this by explicitly expanding all paths which begin with "~"
Link: http://lkml.kernel.org/r/1467127337-11135-5-git-send-email-kieran@bingham.xyz
Signed-off-by: Nikolay Borisov <n.borisov.lkml@gmail.com>
Signed-off-by: Kieran Bingham <kieran@bingham.xyz>
Reviewed-by: Jan Kiszka <jan.kiszka@siemens.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Since scripts/gdb/linux/constants.py is autogenerated, this should have
been added to .gitignore when it was introduced.
Fixes: f197d75fca ("scripts/gdb: provide linux constants")
Link: http://lkml.kernel.org/r/1467127337-11135-4-git-send-email-kieran@bingham.xyz
Signed-off-by: Omar Sandoval <osandov@fb.com>
Signed-off-by: Kieran Bingham <kieran@bingham.xyz>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
The autogenerated constants.py file was only being built on the initial
call, and if the constants.py.in file changed. As we are utilising the
CPP hooks, we can successfully use the call if_changed_dep rules to
determine when to rebuild the file based on it's inclusions.
Link: http://lkml.kernel.org/r/1467127337-11135-3-git-send-email-kieran@bingham.xyz
Signed-off-by: Kieran Bingham <kieran@bingham.xyz>
Reported-by: Jan Kiszka <jan.kiszka@web.de>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
The constants.py generation, involves a rule to link into the main
makefile. This rule has no command and generates a spurious warning
message in the build logs when CONFIG_SCRIPTS_GDB is enabled.
Fix simply by giving a no-op action
Link: http://lkml.kernel.org/r/1467127337-11135-2-git-send-email-kieran@bingham.xyz
Signed-off-by: Kieran Bingham <kieran@bingham.xyz>
Reported-by: Jan Kiszka <jan.kiszka@siemens.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
When a header file is removed from generic-y (often accompanied by the
addition of an arch specific header), the generated wrapper file will
persist, and in some cases may still take precedence over the new arch
header.
For example commit f1fe2d21f4 ("MIPS: Add definitions for extended
context") removed ucontext.h from generic-y in arch/mips/include/asm/,
and added an arch/mips/include/uapi/asm/ucontext.h. The continued use of
the wrapper when reusing a dirty build tree resulted in build failures
in arch/mips/kernel/signal.c:
arch/mips/kernel/signal.c: In function ‘sc_to_extcontext’:
arch/mips/kernel/signal.c:142:12: error: ‘struct ucontext’ has no member named ‘uc_extcontext’
return &uc->uc_extcontext;
^
Fix by detecting and removing wrapper headers in generated header
directories that do not correspond to a filename in generic-y, genhdr-y,
or the newly introduced generated-y.
Reported-by: Jacek Anaszewski <j.anaszewski@samsung.com>
Reported-by: Hauke Mehrtens <hauke@hauke-m.de>
Reported-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Signed-off-by: James Hogan <james.hogan@imgtec.com>
Acked-by: Arnd Bergmann <arnd@arndb.de>
Acked-by: Florian Fainelli <f.fainelli@gmail.com>
Cc: linux-arch@vger.kernel.org
Cc: linux-mips@linux-mips.org
Cc: Paul Burton <paul.burton@imgtec.com>
Cc: linux-kbuild@vger.kernel.org
Cc: Ralf Baechle <ralf@linux-mips.org>
Cc: Michal Marek <mmarek@suse.com>
Link: http://lkml.kernel.org/r/1466808144-23209-3-git-send-email-james.hogan@imgtec.com
Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Move the definition of fsl_mc_device_id to its proper location in
mod_devicetable.h, and add fsl-mc bus support to devicetable-offsets.c
and file2alias.c to enable device table matching. With this patch udev
based module loading of fsl-mc drivers is supported.
Signed-off-by: Stuart Yoder <stuart.yoder@nxp.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
- ptrace: Fix out of bounds array access warning from Khem Raj
- pseries: Fix PCI config address for DDW from Gavin Shan
- pseries: Fix IBM_ARCH_VEC_NRCORES_OFFSET since POWER8NVL was added from Michael Ellerman
- of: fix autoloading due to broken modalias with no 'compatible' from Wolfram Sang
- radix: Fix always false comparison against MMU_NO_CONTEXT from Aneesh Kumar K.V
- hash: Compute the segment size correctly for ISA 3.0 from Aneesh Kumar K.V
- nohash: Fix build break with 64K pages from Michael Ellerman
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1
iQIcBAABAgAGBQJXWpyDAAoJEFHr6jzI4aWAxl8P/0m7sbx8yyExRrRlv0kXPSHX
5LI69fPgU44Vq6KImndN7D0UWxCZeSG6ZJmdEzDonYlPrMtXTC6wkG+tk1l2ov2/
nsatn1HeCqO7W9rniKuFXAnleTZlq3pxPk55JUPySjS+6oIlfkJfNIQpJednNe/b
RFj6HAOJEwKDRguADxJFHPi1ATIF5ahFVkowV0p8aCT2kII+Ixe/4I2RDfQ4oxVg
l3Iq7TLmbl7s2jxIaSA3Qf2FZRgXHqtULWI+sj7uTHaAB/3tfqLf7ITG8VGSM0uQ
cuBEPG/hPuebo0C/kFw3x1hGed7jsmAq8QIHIHBKwJNU3A3NKOoftivfUBuO6FrF
zkkS21GhMNJb+7DZeF+8QPmvG/ORG6YZeZndvFXRyimQHTHP0XGeq86RckQ6zcl6
mh3bEuqIzGV11IIA8JC2FhnRPx+3mSKPfewVZTX0tse+ZzbJWUz3yYB9AQjyAXoY
fbHz9V9HCk4hfwb8CWm0GjVzHitSSDyJouwp0oUz84R+1X4rnPeZLxHMe3bMRI4k
t6R9DmGdoe1Lgefd5SoPEE/sBxq0BMuyIiG6ICK/MW2SCb5VLGGh8bDrSI9vIVvy
2uwfyj1toJlNWB1M08376AWWru7l/VgYW7I+sXJSp86eQ/FmdGChfuo+sn2shQyj
kRoWoakEGUO5f6Ed5qPA
=5kLq
-----END PGP SIGNATURE-----
Merge tag 'powerpc-4.7-3Michael Ellerman:' of git://git.kernel.org/pub/scm/linux/kernel/git/powerpc/linux
Pull powerpc fixes from
- ptrace: Fix out of bounds array access warning from Khem Raj
- pseries: Fix PCI config address for DDW from Gavin Shan
- pseries: Fix IBM_ARCH_VEC_NRCORES_OFFSET since POWER8NVL was added
from Michael Ellerman
- of: fix autoloading due to broken modalias with no 'compatible' from
Wolfram Sang
- radix: Fix always false comparison against MMU_NO_CONTEXT from Aneesh
Kumar K.V
- hash: Compute the segment size correctly for ISA 3.0 from Aneesh
Kumar K.V
- nohash: Fix build break with 64K pages from Michael Ellerman
* tag 'powerpc-4.7-3' of git://git.kernel.org/pub/scm/linux/kernel/git/powerpc/linux:
powerpc/nohash: Fix build break with 64K pages
powerpc/mm/hash: Compute the segment size correctly for ISA 3.0
powerpc/mm/radix: Fix always false comparison against MMU_NO_CONTEXT
of: fix autoloading due to broken modalias with no 'compatible'
powerpc/pseries: Fix IBM_ARCH_VEC_NRCORES_OFFSET since POWER8NVL was added
powerpc/pseries: Fix PCI config address for DDW
powerpc/ptrace: Fix out of bounds array access warning
Scan all input files for EXPORT_SYMBOLs along with the explicitly
specified export files before actually parsing anything.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
If the kernel-doc comments for functions are not in the same file as the
EXPORT_SYMBOL statements, the -export and -internal output selections do
not work as expected. This is typically the case when the kernel-doc
comments are in header files next to the function declarations and the
EXPORT_SYMBOL statements are next to the function definitions in the
source files.
Let the user specify additional source files in which to look for the
EXPORT_SYMBOLs using the new -export-file FILE option, which may be
given multiple times.
The pathological example for this is include/net/mac80211.h, which has
all the kernel-doc documentation for the exported functions defined in a
plethora of source files net/mac80211/*.c.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Since
commit 32217761ee
Author: Jani Nikula <jani.nikula@intel.com>
Date: Sun May 29 09:40:44 2016 +0300
kernel-doc: concatenate contents of colliding sections
we started getting (more) errors on duplicate section names, especially
on the default section name "Description":
include/net/mac80211.h:3174: warning: duplicate section name 'Description'
This is usually caused by a slightly unorthodox placement of parameter
descriptions, like in the above case, and kernel-doc resetting back to
the default section more than once within a kernel-doc comment.
Ignore warnings on the duplicate section name automatically assigned by
kernel-doc, and only consider explicitly user assigned duplicate section
names an issue.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Lots of kerneldoc entries use "example:" or "note:" as section headers.
Until such a time as we can make them use proper markup, make them work as
intended.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Because of an improper dereference, a stray 'C' character was output to
the modalias when no 'compatible' was specified. This is the case for
some old PowerMac drivers which only set the 'name' property. Fix it to
let them match again.
Reported-by: Mathieu Malaterre <malat@debian.org>
Signed-off-by: Wolfram Sang <wsa@the-dreams.de>
Tested-by: Mathieu Malaterre <malat@debian.org>
Cc: Philipp Zabel <p.zabel@pengutronix.de>
Cc: Andreas Schwab <schwab@linux-m68k.org>
Fixes: 6543becf26 ("mod/file2alias: make modalias generation safe for cross compiling")
Cc: stable@vger.kernel.org # v3.9+
Signed-off-by: Michael Ellerman <mpe@ellerman.id.au>
Opt-in since this wreaks the rst output and must be removed
by consumers again. This is useful to adjust the linenumbers
for included kernel-doc snippets in shinx. With that sphinx
error message will be accurate when there's issues with the
rst-ness of the kernel-doc comments.
Especially when transitioning a new docbook .tmpl to .rst this
is extremely useful, since you can just use your editors compilation
quickfix list to accurately jump from error to error.
v2:
- Also make sure that we filter the LINENO for purpose/at declaration
start so it only shows for selected blocks, not all of them (Jani).
While at it make it a notch more accurate.
- Avoid undefined $lineno issues. I tried filtering these out at the
callsite, but Jani spotted more when linting the entire kernel.
Unamed unions and similar things aren't stored consistently and end
up with an undefined line number (but also no kernel-doc text, just
the parameter type). Simplify things and filter undefined line
numbers in print_lineno() to catch them all.
v3: Fix LINENO 0 issue for kernel-doc comments without @param: lines
or any other special sections that directly jump to the description
after the "name - purpose" line. Only really possible for functions
without parameters. Noticed by Jani.
Cc: Jani Nikula <jani.nikula@intel.com>
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
state3 = prototype parsing, so name them accordingly.
Cc: Jani Nikula <jani.nikula@intel.com>
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Further up in the state machinery we switch from STATE_NAME to
STATE_DOCBLOCK when we match /$doc_block/. Which means this block of
code here is entirely unreachable, unless there are multiple DOC:
sections within a single kernel-doc comment.
Getting a list of all the files with more than one DOC: section using
$ git grep -c " * DOC:" | grep -v ":1$"
and then doing a full audit of them reveals there are no such comment
blocks in the kernel.
Supporting multiple DOC: sections in a single kernel-doc comment does
not seem like a recommended way of doing things anyway, so nuke the code
for simplicity.
Cc: Jani Nikula <jani.nikula@intel.com>
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
[Jani: amended the commit message]
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
If the documentation comment does not have params or sections, the
section heading may leak from the previous documentation comment.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
If there are multiple sections with the same section name, the current
implementation results in several sections by the same heading, with the
content duplicated from the last section to all. Even if there's the
error message, a more graceful approach is to combine all the
identically named sections into one, with concatenated contents.
With the supported sections already limited to select few, there are
massively fewer collisions than there used to be, but this is still
useful for e.g. when function parameters are documented in the middle of
a documentation comment, with description spread out above and
below. (This is not a recommended documentation style, but used in the
kernel nonetheless.)
We can now also demote the error to a warning.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
kernel-doc currently identifies anything matching "section header:"
(specifically a string of word characters and spaces followed by a
colon) as a new section in the documentation comment, and renders the
section header accordingly.
Unfortunately, this turns all uses of colon into sections, mostly
unintentionally. Considering the output, erroneously creating sections
when not intended is always worse than erroneously not creating sections
when intended. For example, a line with "http://example.com" turns into
a "http" heading followed by "//example.com" in normal text style, which
is quite ugly. OTOH, "WARNING: Beware of the Leopard" is just fine even
if "WARNING" does not turn into a heading.
It is virtually impossible to change all the kernel-doc comments, either
way. The compromise is to pick the most commonly used and depended on
section headers (with variants) and accept them as section headers.
The accepted section headers are, case insensitive:
* description:
* context:
* return:
* returns:
Additionally, case sensitive:
* @return:
All of the above are commonly used in the kernel-doc comments, and will
result in worse output if not identified as section headers. Also,
kernel-doc already has some special handling for all of them, so there's
nothing particularly controversial in adding more special treatment for
them.
While at it, improve the whitespace handling surrounding section
names. Do not consider the whitespace as part of the name.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
If a param description spans multiple lines, check any leading
whitespace in the first continuation line, and remove same amount of
whitespace from following lines.
This allows indentation in the multi-line parameter descriptions for
aesthetical reasons while not causing accidentally significant
indentation in the rst output.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Handle whitespace on the first line of param text as if it was the empty
string. There is no need to add the newline in this case. This improves
the rst output in particular, where blank lines may be problematic in
parameter lists.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Move away from field lists, and simply use **strong emphasis** for
section headings on lines of their own. Do not use rst section headings,
because their nesting depth depends on the surrounding context, which
kernel-doc has no knowledge of. Also, they do not need to end up in any
table of contexts or indexes.
There are two related immediate benefits. Field lists are typically
rendered in two columns, while the new style uses the horizontal width
better. With no extra indent on the left, there's no need to be as fussy
about it. Field lists are more susceptible to indentation problems than
the new style.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
The inline member markup allows whitespace lines before the actual
documentation starts. Strip the leading blank lines. This improves the
rst output.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
The use of these is confusing in the script, and per this grep, they're
not used anywhere anyway:
$ git grep " \* [%$&][a-zA-Z0-9_]*:" -- *.[ch] | grep -v "\$\(Id\|Revision\|Date\)"
While at it, throw out the constants array, nothing is ever put there
again.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
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>
Pull misc kbuild updates from Michal Marek:
"This is the non-critical part of kbuild:
- Coccinelle fixes, one semantic patch less in this round [Vaishali
Thakkar, Wolfram Sang, Kees Cook]
- rpm-pkg support for (open)SUSE's update-bootloader [Jiří Kosian]
- rpm-pkg restored support for $RPMOPTS [Srinivas Pandruvada]
- deb-pkg fixes for the linux-headers package [Bjørn Mork, Azriel
Samson]"
* 'misc' of git://git.kernel.org/pub/scm/linux/kernel/git/mmarek/kbuild:
coccicheck: Fix missing 0 index in kill loop
scripts/package/Makefile: rpmbuild add support of RPMOPTS
builddeb: fix missing headers in linux-headers package
builddeb: include objtool binary in headers package
kbuild/mkspec: support 'update-bootloader'-based systems
scripts: coccinelle: remove check to move constants to right
Coccinelle: setup_timer: Add space in front of parentheses
Pull kconfig update from Michal Marek:
- fix for behavior of tristate choice items and fix for documentation
of existing kconfig behavior [Dirk Gouders]
- more helpful "unexpected data" kconfig warning [Paul Bolle]
* 'kconfig' of git://git.kernel.org/pub/scm/linux/kernel/git/mmarek/kbuild:
kconfig/symbol.c: handle choice_values that depend on 'm' symbols
kconfig-language: elaborate on the type of a choice
kconfig-language: fix comment on dependency-generated menu structures.
kconfig: add unexpected data itself to warning
