Commit Graph

173 Commits

Author SHA1 Message Date
Markus Heiser
463a0fdc3e kernel-doc parser mishandles declarations split into lines
Reported by Johannes Berg [1].  Problem here: function
process_proto_type() concatenates the striped lines of declaration
without any whitespace. A one-liner of::

 struct something {
       struct foo
       bar;
       };

has to be::

 struct something {struct foo bar;};

Without the patching process_proto_type(), the result missed the space
between 'foo' and 'bar'::

 struct something {struct foobar;};

Bugfix of process_proto_type() brings next error when blank lines
between enum declaration::

 warning: Enum value ' ' not described in enum 'foo'

Problem here: dump_enum() does not strip leading whitespaces from
the concatenated string (with the new additional space from
process_proto_type).

[1] https://www.mail-archive.com/linux-doc@vger.kernel.org/msg12410.html

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-08-30 16:18:16 -06:00
Linus Torvalds
16ffc4c394 Kbuild misc updates for 4.13
- Use more portable shebang for Perl scripts
 
 - Remove trailing spaces from GCC version in kernel log
 
 - Make initramfs generation deterministic
 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1
 
 iQIcBAABAgAGBQJZXrq2AAoJED2LAQed4NsGzlIP/jmVGusmFIP2jFC7zUEVaKsp
 VK4tezn0aa/c/BsY+kGu3OVqUHgspQSjNa4wH27A+z4/skkxPQKUmF1IY+8/W5yc
 aR0Yn76vzjjNYNl6AS3fA+QP+dBn+UdQDA2jMNKyu/3fACjiVY9BBx2ZdhJMwJcy
 WrAax/fQNnRjmAQFQpptNBvYZn1B7A/7iFCPpQbPP6GFsqSJ2zMtRGjtoaeFgpV3
 On6d4uAcgAcnEHw1zomWTx0N0LghW+L6Te9PoHyPZnyxfi+OVN/bmakoy7qs1uUh
 zWucIhpBc8bshx6s4VnJ5OZhFNVEkeSjq5CivYKnU0u4waKb7suxuI1+D6e7uRrA
 2OuXmhm7sRvGHwGIxEdJAOlF0PNecYSgJPv+ZDcOxVMy72REUZUEjgThti/vLdUn
 9iVDXn/ExOxqJW7isth1MTn3FBsDUIZDKK5EypgY/oAuECR6pQnjD3HjojJBACau
 OqbsZDPqmDiY3sxzU1GcAbrhAJiGyWXV7hAKsROoVlgwU2fu0Al2HHtDzEjqLrzK
 wIvAD+lsWKiFP1zXlCnrsgjXgn/RFG1cHLiqEhtPy+HpqNzXoXDRs5kcTsr5Z0fj
 3DlMNqa7Bv0raL3+XG2pp9OR5gWdLxmOuPIR/TNU3JubTRur4SElJtXyDoHVTJti
 s4mye73xjjcifGEwpZQw
 =C+WJ
 -----END PGP SIGNATURE-----

Merge tag 'kbuild-misc-v4.13' of git://git.kernel.org/pub/scm/linux/kernel/git/masahiroy/linux-kbuild

Pull misc Kbuild updates from Masahiro Yamada:

 - Use more portable shebang for Perl scripts

 - Remove trailing spaces from GCC version in kernel log

 - Make initramfs generation deterministic

* tag 'kbuild-misc-v4.13' of git://git.kernel.org/pub/scm/linux/kernel/git/masahiroy/linux-kbuild:
  kbuild: create deterministic initramfs directory listings
  scripts/mkcompile_h: Remove trailing spaces from compiler version
  scripts: Switch to more portable Perl shebang
2017-07-07 15:09:09 -07:00
Jakub Kicinski
1cb566ba56 scripts/kernel-doc: handle DECLARE_HASHTABLE
DECLARE_HASHTABLE needs similar handling to DECLARE_BITMAP
because otherwise kernel-doc assumes the member name is the
second, not first macro parameter.

Signed-off-by: Jakub Kicinski <jakub.kicinski@netronome.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-07-03 06:57:09 -06:00
Kamil Rytarowski
cb77f0d623 scripts: Switch to more portable Perl shebang
The default NetBSD package manager is pkgsrc and it installs Perl
along other third party programs under custom and configurable prefix.
The default prefix for binary prebuilt packages is /usr/pkg, and the
Perl executable lands in /usr/pkg/bin/perl.

This change switches "/usr/bin/perl" to "/usr/bin/env perl" as it's
the most portable solution that should work for almost everybody.
Perl's executable is detected automatically.

This change switches -w option passed to the executable with more
modern "use warnings;" approach. There is no functional change to the
default behavior.

While there, drop "require 5" from scripts/namespace.pl (Perl from 1994?).

Signed-off-by: Kamil Rytarowski <n54@gmx.com>
Signed-off-by: Masahiro Yamada <yamada.masahiro@socionext.com>
2017-05-14 11:20:44 +09:00
Mauro Carvalho Chehab
f9b5c5304c scripts/kernel-doc: fix handling of parameters with parenthesis
lib/crc32c defines one parameter as:
	const u32 (*tab)[256]

Better handle parenthesis, to avoid those warnings:

./lib/crc32.c:149: warning: No description found for parameter 'tab)[256]'
./lib/crc32.c:149: warning: Excess function parameter 'tab' description in 'crc32_le_generic'
./lib/crc32.c:294: warning: No description found for parameter 'tab)[256]'
./lib/crc32.c:294: warning: Excess function parameter 'tab' description in 'crc32_be_generic'

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-04-02 14:06:56 -06:00
Mauro Carvalho Chehab
b97f193abf scripts/kernel-doc: fix parser for apostrophes
On ReST, adding a text like ``literal`` is valid. However,
the kernel-doc script won't handle it fine.

We really need this feature, in order to escape things like
%ph, with is found on some C files.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-04-02 14:06:50 -06:00
Matthew Wilcox
5a0bc578e0 kernel-doc: Handle returning pointers to pointers
Clearly nobody ever tried to build the documentation for the radix tree
before:

include/linux/radix-tree.h:400: warning: cannot understand function
prototype: 'void ** radix_tree_iter_init(struct radix_tree_iter *iter,
unsigned long start) '

Indeed, the regexes only handled a single '*', not one-or-more.  I have
tried to fix that, but now I have perl regexes all over my hands, and
I fear I shall never be clean again.

Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-01-26 15:20:10 -07:00
Gabriel Krisman Bertazi
ada5f446bb kernel-doc: properly document array arguments of function
Documentation for array parameters passed in a function, like the first
argument in the function below, weren't getting exported in the rst
format, although they work fine for html and pdf formats:

  void drm_clflush_pages(struct page * pages[], unsigned long num_pages)

That's because the string key to store the description in the
parameterdescs dictionary doesn't have the [] suffix.  This cleans up
the suffix from the key before accessing the dictionary.

Signed-off-by: Gabriel Krisman Bertazi <krisman@collabora.co.uk>
Fixes: c0d1b6ee78 ("kernel-doc: produce RestructuredText output")
Reviewed-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-01-13 10:53:24 -07:00
Paolo Bonzini
df31175bb4 kernel-doc: make highlights more homogenous for the various backends
$type_struct_full and friends are only used by the restructuredText
backend, because it needs to separate enum/struct/typedef/union from
the name of the type.  However, $type_struct is *also* used by the rST
backend.  This is confusing.

This patch replaces $type_struct's use in the rST backend with a new
$type_fallback; it modifies $type_struct so that it can be used in the
rST backend; and creates regular expressions like $type_struct
for enum/typedef/union, for use in all backends.

Note that, compared to $type_*_full, in the new regexes $1 includes both
the "kind" and the name (before, $1 was pretty much a constant).

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Acked-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-01-04 15:08:14 -07:00
Paolo Bonzini
5267dd354b kernel-doc: make member highlighting available in all backends
Note that, in order to produce the correct Docbook markup, the "." or "->"
must be separated from the member name in the regex's captured fields.  For
consistency, this change is applied to $type_member and $type_member_func
too, not just to $type_member_xml.

List mode only prints the struct name, to avoid any undesired change in
the operation of docproc.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Acked-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-01-04 15:08:03 -07:00
Paolo Bonzini
fc6d7af89f kernel-doc: include parameter type in docbook output
The restructuredText output includes both the parameter type and
the name for functions and function-typed members.  Do the same
for docbook.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Acked-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-01-04 15:07:53 -07:00
Paolo Bonzini
b1aaa546b5 kernel-doc: strip attributes even if they have an argument
An inline function can have an attribute, as in include/linux/log2.h,
and kernel-doc handles this already for simple cases.  However,
some attributes have arguments (e.g. the "target" attribute).
Handle those too.

Furthermore, attributes could be at the beginning of a function
declaration, before the return type.  To correctly handle this case,
you need to strip spaces after the attributes; otherwise, dump_function
is left confused.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Acked-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-01-04 15:07:42 -07:00
Paolo Bonzini
02a4f4fe52 kernel-doc: cleanup parameter type in function-typed arguments
A prototype like

    /**
     * foo - sample definition
     * @bar: a parameter
     */
    int foo(int (*bar)(int x,
                       int y));

is currently producing

    .. c:function:: int foo (int (*bar) (int x,                    int y)

       sample definition

    **Parameters**

    ``int (*)(int x,                    int y) bar``
      a parameter

Collapse the spaces so that the output is nicer.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Acked-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-01-04 15:07:23 -07:00
Jani Nikula
0c9aa20957 kernel-doc: add support for one line inline struct member doc comments
kernel-doc supports documenting struct members "inline" since
a4c6ebede2 ("scripts/kernel-doc Allow struct arguments documentation
in struct body"). This requires the inline kernel-doc comments to have
the opening and closing comment markers (/** and */ respectively) on
lines of their own, even for short comments. For example:

	/**
	 * struct foo - struct documentation
	 */
	struct foo {
		/**
		 * @bar: member documentation
		 */
		int bar;
	};

Add support for one line inline comments:

	/**
	 * struct foo - struct documentation
	 */
	struct foo {
		/** @bar: member documentation */
		int bar;
	};

Note that mixing of the two in one doc comment is not allowed; either
both comment markers must be on lines of their own, or both must be on
the one line. This limitation keeps both the comments more uniform, and
kernel-doc less complicated.

Cc: Daniel Vetter <daniel@ffwll.ch>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-16 16:30:27 -07:00
Silvio Fricke
c950a1739e kernel-doc: better parsing of named variable arguments
Without this patch we get warnings for named variable arguments.

    warning: No description found for parameter '...'
    warning: Excess function parameter 'args' description in 'alloc_ordered_workqueue'

Signed-off-by: Silvio Fricke <silvio.fricke@gmail.com>
Reviewed-by: Jani Nikula <jani.nikula@intel.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-10-28 10:54:16 -06:00
Jonathan Corbet
5219f18aaf docs: Special-case function-pointer parameters in kernel-doc
Add yet another regex to kernel-doc to trap @param() references separately
and not produce corrupt RST markup.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-06 08:02:49 -06:00
Jonathan Corbet
ef00028b20 docs: make kernel-doc handle varargs properly
As far as I can tell, the handling of "..." arguments has never worked
right, so any documentation provided was ignored in favor of "variable
arguments."  This makes kernel-doc handle "@...:" as documented.  It does
*not* fix spots in kerneldoc comments that don't follow that convention,
but they are no more broken than before.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-06 08:02:19 -06:00
Mauro Carvalho Chehab
82801d065b docs-rst: kernel-doc: fix typedef output in RST format
When using a typedef function like this one:
	typedef bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);

The Sphinx C domain expects it to create a c:type: reference,
as that's the way it creates the type references when parsing
a c:function:: declaration.

So, a declaration like:

	.. c:function:: bool v4l2_valid_dv_timings (const struct v4l2_dv_timings * t, const struct v4l2_dv_timings_cap * cap, v4l2_check_dv_timings_fnc fnc, void * fnc_handle)

Will create a cross reference for :c:type:`v4l2_check_dv_timings_fnc`.

So, when outputting such typedefs in RST format, we need to handle
this special case, as otherwise it will produce those warnings:

	./include/media/v4l2-dv-timings.h:43: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
	./include/media/v4l2-dv-timings.h:60: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
	./include/media/v4l2-dv-timings.h:81: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc

So, change the kernel-doc script to produce a RST output for the
above typedef as:
	.. c:type:: v4l2_check_dv_timings_fnc

	   **Typedef**: timings check callback

	**Syntax**

	  ``bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);``

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-01 08:10:07 -06:00
Mauro Carvalho Chehab
d37c43ce19 docs-rst: improve typedef parser
Improve the parser to handle typedefs like:

	typedef bool v4l2_check_dv_timings_fnc(const struct v4l2_dv_timings *t, void *handle);

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-01 08:07:22 -06:00
Mauro Carvalho Chehab
6d232c8015 docs-rst: kernel-doc: better output struct members
Right now, for a struct, kernel-doc produces the following output:

	.. c:type:: struct v4l2_prio_state

	   stores the priority states

	**Definition**

	::

	  struct v4l2_prio_state {
	    atomic_t prios[4];
	  };

	**Members**

	``atomic_t prios[4]``
	  array with elements to store the array priorities

Putting a member name in verbatim and adding a continuation line
causes the LaTeX output to generate something like:
	item[atomic_t prios\[4\]] array with elements to store the array priorities

Everything inside "item" is non-breakable, with may produce
lines bigger than the column width.

Also, for function members, like:

        int (* rx_read) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num);

It puts the name of the member at the end, like:

        int (*) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num) read

With is very confusing.

The best is to highlight what really matters: the member name.
is a secondary information.

So, change kernel-doc, for it to produce the output on a different way:

	**Members**

	``prios[4]``

	  array with elements to store the array priorities

Also, as the type is not part of LaTeX "item[]", LaTeX will split it into
multiple lines, if needed.

So, both LaTeX/PDF and HTML outputs will look good.

It should be noticed, however, that the way Sphinx LaTeX output handles
things like:

	Foo
	   bar

is different than the HTML output. On HTML, it will produce something
like:

	**Foo**
	   bar

While, on LaTeX, it puts both foo and bar at the same line, like:

	**Foo** bar

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-24 15:24:36 -06:00
Markus Heiser
aa10a78266 doc-rst: Revert "kernel-doc: fix handling of address_space tags"
This reverts commit a88b1672d4.

From the origin comit log::

  The RST cpp:function handler is very pedantic: it doesn't allow any
  macros like __user on it

Since the kernel-doc parser does NOT make use of the cpp:domain, there
is no need to change the kernel-doc parser eleminating the address_space
tags.

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-22 15:19:53 -06:00
Mauro Carvalho Chehab
a88b1672d4 doc-rst: kernel-doc: fix handling of address_space tags
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>
2016-07-22 15:34:24 -06:00
Daniel Vetter
e7ca311e37 kernel-doc: Fix up warning output
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>
2016-07-17 20:38:35 -06:00
Jani Nikula
c9b2cfb3fa kernel-doc: unify all EXPORT_SYMBOL scanning to one place
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>
2016-06-10 11:29:20 +03:00
Jani Nikula
88c2b57da4 kernel-doc: add support for specifying extra files for EXPORT_SYMBOLs
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>
2016-06-10 11:29:19 +03:00
Jani Nikula
1ad560e43c kernel-doc: abstract filename mapping
Reduce duplication in follow-up work. No functional changes.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-06-10 11:29:19 +03:00
Jani Nikula
da9726ecfb kernel-doc: add missing semi-colons in option parsing
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-06-10 11:29:18 +03:00
Jani Nikula
95b6be9d19 kernel-doc: do not warn about duplicate default section names
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>
2016-06-10 11:29:18 +03:00
Jani Nikula
5668604a6c kernel-doc: remove old debug cruft from dump_section()
No functional changes.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-06-10 11:29:05 +03:00
Jonathan Corbet
8569de68e7 docs: kernel-doc: Add "example" and "note" to the magic section types
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>
2016-06-09 13:35:05 -06:00
Daniel Vetter
0b0f5f29b2 scripts/kernel-doc: Add option to inject line numbers
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>
2016-06-04 11:35:31 +03:00
Daniel Vetter
b7afa92b55 scripts/kernel-doc: Also give functions symbolic names
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>
2016-06-03 11:41:01 +03:00
Daniel Vetter
ebff7f929b scripts/kernel-doc: Remove duplicated DOC: start handling
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>
2016-06-03 11:26:39 +03:00
Jani Nikula
2f4ad40a05 kernel-doc: reset contents and section harder
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>
2016-05-30 13:39:04 +03:00
Jani Nikula
32217761ee kernel-doc: concatenate contents of colliding sections
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>
2016-05-30 13:39:03 +03:00
Jani Nikula
f624adef3d kernel-doc: limit the "section header:" detection to a select few
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>
2016-05-30 13:39:03 +03:00
Jani Nikula
cddfe325af kernel-doc/rst: remove fixme comment
Yes, for our purposes the type should contain typedef.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-05-30 13:39:02 +03:00
Jani Nikula
d4b08e0cd2 kernel-doc/rst: use *undescribed* instead of _undescribed_
The latter isn't special to rst.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-05-30 13:39:02 +03:00
Jani Nikula
b7886de43c kernel-doc: strip leading whitespace from continued param descs
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>
2016-05-30 13:39:01 +03:00
Jani Nikula
0a7263014b kernel-doc: improve handling of whitespace on the first line param description
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>
2016-05-30 13:39:01 +03:00
Jani Nikula
ecbcfba126 kernel-doc/rst: change the output layout
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>
2016-05-30 13:39:00 +03:00
Jani Nikula
6450c8957e kernel-doc: strip leading blank lines from inline doc comments
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>
2016-05-30 13:39:00 +03:00
Jani Nikula
830066a7a3 kernel-doc/rst: blank lines in output are not needed
Current approach leads to two blank lines, while one is enough.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-05-30 13:38:59 +03:00
Jani Nikula
a0b96c2dbd kernel-doc: fix wrong code indentation
No functional changes.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-05-30 13:38:59 +03:00
Jani Nikula
13901ef27c kernel-doc: do not regard $, %, or & prefixes as special in section names
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>
2016-05-30 13:38:59 +03:00
Jani Nikula
c099ff6989 kernel-doc/rst: highlight function/struct/enum purpose lines too
Let the user use @foo, &bar, %baz, etc. in the first kernel-doc purpose
line too.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-05-30 13:38:58 +03:00
Jani Nikula
9c9193c49c kernel-doc/rst: drop redundant unescape in highlighting
This bit is already done by xml_unescape() above.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-05-30 13:38:58 +03:00
Jani Nikula
f3341dcf3b kernel-doc/rst: add support for struct/union/enum member references
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>
2016-05-30 13:38:57 +03:00
Jani Nikula
47ae7aed34 kernel-doc/rst: add support for &union foo and &typedef foo references
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>
2016-05-30 13:38:57 +03:00
Jani Nikula
a7291e7e03 kernel-doc/rst: &foo references are more universal than structs
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>
2016-05-30 13:38:56 +03:00