Skip to content

L
linux
Switch branch/tag
  1. 23 Jun, 2016 6 commits
  3. 10 Jun, 2016 9 commits
  5. 09 Jun, 2016 3 commits
    • Jonathan Corbet's avatar
      docs: kernel-doc: Add "example" and "note" to the magic section types · 8569de68
      Jonathan Corbet authored 
      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: default avatarJonathan Corbet <corbet@lwn.net>
      8569de68
    • Kees Cook's avatar
      docs: self-protection: rename "leak" to "exposure" · c9de4a82
      Kees Cook authored 
      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: default avatarKees Cook <keescook@chromium.org>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
      c9de4a82
    • Jonathan Corbet's avatar
      Merge branch 'sphinx-for-docs-next' into doc/4.8 · 6d5244c7
      Jonathan Corbet authored 
      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.
      6d5244c7
  7. 04 Jun, 2016 2 commits
    • Daniel Vetter's avatar
      doc/sphinx: Track line-number of starting blocks · d90368f2
      Daniel Vetter authored 
      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 <jani.nikula@intel.com>
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: default avatarDaniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: default avatarJani Nikula <jani.nikula@intel.com>
      d90368f2
    • Daniel Vetter's avatar
      scripts/kernel-doc: Add option to inject line numbers · 0b0f5f29
      Daniel Vetter authored 
      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: default avatarDaniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: default avatarJani Nikula <jani.nikula@intel.com>
      0b0f5f29
  9. 03 Jun, 2016 8 commits
  11. 01 Jun, 2016 2 commits
  13. 30 May, 2016 10 commits
    • Jani Nikula's avatar
      kernel-doc: reset contents and section harder · 2f4ad40a
      Jani Nikula authored 
      If the documentation comment does not have params or sections, the
section heading may leak from the previous documentation comment.
Signed-off-by: default avatarJani Nikula <jani.nikula@intel.com>
      2f4ad40a
    • Jani Nikula's avatar
      kernel-doc: concatenate contents of colliding sections · 32217761
      Jani Nikula authored 
      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: default avatarJani Nikula <jani.nikula@intel.com>
      32217761
    • Jani Nikula's avatar
      kernel-doc: limit the "section header:" detection to a select few · f624adef
      Jani Nikula authored 
      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: default avatarJani Nikula <jani.nikula@intel.com>
      f624adef
    • Jani Nikula's avatar
      kernel-doc/rst: remove fixme comment · cddfe325
      Jani Nikula authored 
      Yes, for our purposes the type should contain typedef.
Signed-off-by: default avatarJani Nikula <jani.nikula@intel.com>
      cddfe325
    • Jani Nikula's avatar
      kernel-doc/rst: use *undescribed* instead of _undescribed_ · d4b08e0c
      Jani Nikula authored 
      The latter isn't special to rst.
Signed-off-by: default avatarJani Nikula <jani.nikula@intel.com>
      d4b08e0c
    • Jani Nikula's avatar
      kernel-doc: strip leading whitespace from continued param descs · b7886de4
      Jani Nikula authored 
      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: default avatarJani Nikula <jani.nikula@intel.com>
      b7886de4
    • Jani Nikula's avatar
      kernel-doc: improve handling of whitespace on the first line param description · 0a726301
      Jani Nikula authored 
      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: default avatarJani Nikula <jani.nikula@intel.com>
      0a726301
    • Jani Nikula's avatar
      kernel-doc/rst: change the output layout · ecbcfba1
      Jani Nikula authored 
      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: default avatarJani Nikula <jani.nikula@intel.com>
      ecbcfba1
    • Jani Nikula's avatar
      kernel-doc: strip leading blank lines from inline doc comments · 6450c895
      Jani Nikula authored 
      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: default avatarJani Nikula <jani.nikula@intel.com>
      6450c895
    • Jani Nikula's avatar
      kernel-doc/rst: blank lines in output are not needed · 830066a7
      Jani Nikula authored 
      Current approach leads to two blank lines, while one is enough.
Signed-off-by: default avatarJani Nikula <jani.nikula@intel.com>
      830066a7
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7