01 Jul, 2016
1 commit
-
Implements the reST flat-table directive.
The ``flat-table`` is a double-stage list similar to the ``list-table`` with
some additional features:* column-span: with the role ``cspan`` a cell can be extended through
additional columns* row-span: with the role ``rspan`` a cell can be extended through
additional rows* auto span rightmost cell of a table row over the missing cells on the right
side of that table-row. With Option ``:fill-cells:`` this behavior can
changed from *auto span* to *auto fill*, which automaticly inserts (empty)list tables
The *list tables* formats are double stage lists. Compared to the
ASCII-art they migth be less comfortable for readers of the
text-files. Their advantage is, that they are easy to create/modify
and that the diff of a modification is much more meaningfull, because
it is limited to the modified content.The initial implementation was taken from the sphkerneldoc project [1]
[1] https://github.com/return42/sphkerneldoc/commits/master/scripts/site-python/linuxdoc/rstFlatTable.py
Signed-off-by: Markus Heiser
[jc: fixed typos and misspellings in the docs]
Signed-off-by: Jonathan Corbet
24 Jun, 2016
1 commit
-
Describe Sphinx, reStructuredText, the kernel-doc extension, the
kernel-doc structured documentation comments, etc.The kernel-doc parts are based on kernel-doc-nano-HOWTO.txt, by Tim
.Signed-off-by: Jani Nikula
Signed-off-by: Jonathan Corbet
23 Jun, 2016
6 commits
-
Signed-off-by: Michal Nazarewicz
Signed-off-by: Jonathan Corbet -
In the current Documentation/md.txt, the lower limit value of
stripe_cache_size is 16 and the default value is 128, but when
I update kernel to the latest mainline version and RAID5 array
is created by mdadm, then execute the following commands, it
shows an error and a difference respectively.1) set stripe_cache_size to 16
[root@localhost ~]# echo 16 > /sys/block/md0/md/stripe_cache_size
bash: echo: write error: Invalid argument
2) read the default value of stripe_cache_size
[root@localhost ~]# cat /sys/block/md0/md/stripe_cache_size
256I read drivers/md/raid5.c and find the following related code:
1) in function 'raid5_set_cache_size':
if (size 32768)
return -EINVAL;
2) #define NR_STRIPES 256So the lower limit value of stripe_cache_size should be 17 and
the default value should be 256.Signed-off-by: Tiezhu Yang
Signed-off-by: Jonathan Corbet -
Signed-off-by: Eric Wheeler
Cc: Marc MERLIN
Signed-off-by: Jonathan Corbet -
Bcache documentation updates:
- Added new HOWTO/COOKBOOK section
- fixed a few typos
- /sys/block/bcache0/cache_mode is /sys/block/bcache0/bcache/cache_modeSigned-off-by: Marc MERLIN
Signed-off-by: Jonathan Corbet -
While there's slight overlap with the DocBook help now, this can stay
intact when the DocBook help goes away.Signed-off-by: Jani Nikula
-
The modindex is for python modules.
Signed-off-by: Jani Nikula
10 Jun, 2016
12 commits
-
Let the user specify file patterns where to look for the EXPORT_SYMBOLs
in addition to the file with kernel-doc comments. This is directly based
on the -export-file FILE option added to kernel-doc in "kernel-doc: add
support for specifying extra files for EXPORT_SYMBOLs", but we extend
that with globbing patterns in the Sphinx extension.The file patterns are added as options to the :export: and :internal:
arguments of the kernel-doc directive. For example, to extract the
documentation of exported functions from include/net/mac80211.h:.. kernel-doc:: include/net/mac80211.h
:export: net/mac80211/*.cWithout the file pattern, no exported functions would be found, as the
EXPORT_SYMBOLs are placed in the various source files under
net/mac80211.The matched files are also added as dependencies on the document in
Sphinx, as they may affect the output. This is one of the reasons to do
the globbing in the Sphinx extension instead of in scripts/kernel-doc.The file pattern remains optional, and is not needed if the kernel-doc
comments and EXPORT_SYMBOLs are placed in the source file passed in as
the main argument to the kernel-doc directive. This is the most common
case across the kernel source tree.Signed-off-by: Jani Nikula
-
Using the default str.split doesn't return empty strings like the
current version does.Signed-off-by: Jani Nikula
-
Leftover cruft. No functional changes.
Signed-off-by: Jani Nikula
-
Scan all input files for EXPORT_SYMBOLs along with the explicitly
specified export files before actually parsing anything.Signed-off-by: Jani Nikula
-
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
-
Reduce duplication in follow-up work. No functional changes.
Signed-off-by: Jani Nikula
-
Signed-off-by: Jani Nikula
-
Since
commit 32217761ee9db0215350dfe1ca4e66f312fb8c54
Author: Jani Nikula
Date: Sun May 29 09:40:44 2016 +0300kernel-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
-
No functional changes.
Signed-off-by: Jani Nikula
-
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
-
The meaning of "leak" can be both "untracked resource allocation" and
"memory content disclosure". This document's use was entirely of the
latter meaning, so avoid the confusion by using the Common Weakness
Enumeration name for this: Information Exposure (CWE-200). Additionally
adds a section on structure randomization.Signed-off-by: Kees Cook
Signed-off-by: Jonathan Corbet -
Jani Nikula says:
Jon, this is v2 of [1] and [2], with a considerable amount of polish and
fixes added. We started dogfooding this within drm-intel, and Daniel has
reviewed the lot and contributed a number of fixes, most notably
accurate file and line number references from Sphinx build
errors/warnings to the kernel-doc comments in source code.We believe this is now in good shape for merging for v4.8. It's all in
my sphinx-for-docs-next branch that you've already looked at; pull
details below.When this lands in docs-next and we can backmerge to drm, we'll plunge
ahead and convert gpu.tmpl to rst, and have that ready for v4.8. We
think it's best to contribute that via the drm tree, as it'll involve
splitting up the documentation and likely numerous updates to kernel-doc
comments.I plan to update Documentation/kernel-doc-nano-HOWTO.txt for Sphinx and
rst, obviously converting it to rst while at it.
04 Jun, 2016
7 commits
-
Design is pretty simple: kernel-doc inserts breadcrumbs with line
numbers, and sphinx picks them up. At first I went with a sphinx
comment, but inserting those at random places seriously upsets the
parser, and must be filtered. Hence why this version now uses "#define
LINEO " since one of these ever escape into output it's pretty clear
there is a bug.It seems to work well, and at least the 2-3 errors where sphinx
complained about something that was not correct in kernel-doc text the
line numbers matched up perfectly.v2: Instead of noodling around in the parser state machine, create
a ViewList and parse it ourselves. This seems to be the recommended
way, per Jani's suggestion.v3:
- Split out ViewList pach. Splitting the kernel-doc changes from the
sphinx ones isn't possible, since emitting the LINENO lines wreaks
havoc with the rst formatting. We must filter them.- Improve the regex per Jani's suggestions, and compile it just once
for speed.- Now that LINENO lines are eaten, also add them to function parameter
descriptions. Much less content and offset than for in-line struct
member descriptions, but still nice to know which exact continuation
line upsets sphinx.- Simplify/clarify the line +/-1 business a bit.
v4: Split out the scripts/kernel-doc changes and make line-numbers
opt-in, as suggested by Jani.Cc: Jani Nikula
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet
Signed-off-by: Daniel Vetter
Signed-off-by: Jani Nikula -
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
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet
Signed-off-by: Daniel Vetter
Signed-off-by: Jani Nikula -
Signed-off-by: Niklas Söderlund
Signed-off-by: Jonathan Corbet -
Chinese version CodingStyle is a little outdate, it should be updated.
This patch sync with the latest CodingStyle of all changes,
new chapters (chapter 19 and chapter 20) have been translated.Signed-off-by: Andy Deng
Signed-off-by: Jonathan Corbet -
It took me browsing through the source code to determine that I was,
indeed, using the wrong delimiter in my command lines. So I might as
well document it for the next person.Signed-off-by: Brian Norris
Acked-by: Steven Rostedt
Signed-off-by: Jonathan Corbet -
The compilation emits a warning in function ‘snprintf’,
inlined from ‘set_cmdline’ at
../Documentation/mic/mpssd/mpssd.c:1541:9:
/usr/include/x86_64-linux-gnu/bits/stdio2.h:64:10:
warning: call to __builtin___snprintf_chk will always overflow
destination bufferThis was introduced in commit f4a66c204482 ("misc: mic: Update MIC host
daemon with COSM changes") and is fixed by reverting the changes to the
size argument of these snprintf statements.Cc: Ashutosh Dixit
Signed-off-by: Mike Danese
Signed-off-by: Jonathan Corbet -
There are two sentences in the Sync File documentation where the
english is a little off. This patch is an attempt to fix these.Signed-off-by: Javier Martinez Canillas
Reviewed-by: Gustavo Padovan
Signed-off-by: Jonathan Corbet
03 Jun, 2016
3 commits
-
state3 = prototype parsing, so name them accordingly.
Cc: Jani Nikula
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet
Signed-off-by: Daniel Vetter
Signed-off-by: Jani Nikula -
Instead of just forcefully inserting our kernel-doc input and letting
the state machine stumble over it the recommended way is to create
ViewList, parse that and then return the list of parsed nodes.Suggested by Jani.
Cc: Jani Nikula
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet
Signed-off-by: Daniel Vetter
Signed-off-by: Jani Nikula -
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
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet
Signed-off-by: Daniel Vetter
[Jani: amended the commit message]
Signed-off-by: Jani Nikula
01 Jun, 2016
2 commits
-
With this error output becomes almost readable. The line numbers are
still totally bonghits, but that's a lot harder to pull out of
kerneldoc. We'd essentially have to insert some special markers in the
kernel-doc output, split the output along these markers and then
insert each block separately usingstate_machine.insert_input(block, source, first_line)
Cc: Jani Nikula
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet
Signed-off-by: Daniel Vetter
Signed-off-by: Jani Nikula -
Reconcile differences between python2 and python3 on dealing with
stdout, stderr from Popen. This fixes "name 'unicode' is not defined"
errors on python3. We'll need to try to keep the extension working on
both python-sphinx and python3-sphinx so we don't need two copies.Reported-and-tested-by: Marius Vlad
Signed-off-by: Jani Nikula
30 May, 2016
8 commits
-
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
-
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
-
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
-
Yes, for our purposes the type should contain typedef.
Signed-off-by: Jani Nikula
-
The latter isn't special to rst.
Signed-off-by: Jani Nikula
-
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
-
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
-
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