Skip to content

cloud-kernel
cloud-kernel

openanolis / cloud-kernel
1 年多 前同步成功

通知 161
Star 36
Fork 7
cloud-kernel
cloud-kernel
切换分支/标签
  1. 03 4月, 2017 2 次提交
  3. 27 1月, 2017 1 次提交
  5. 14 1月, 2017 1 次提交
  7. 05 1月, 2017 5 次提交
  9. 17 11月, 2016 1 次提交
    • J
      kernel-doc: add support for one line inline struct member doc comments · 0c9aa209
      由 Jani Nikula 提交于 
      kernel-doc supports documenting struct members "inline" since
a4c6ebed ("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: NJani Nikula <jani.nikula@intel.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      0c9aa209
  11. 29 10月, 2016 1 次提交
  13. 06 9月, 2016 2 次提交
  15. 01 9月, 2016 2 次提交
    • M
      docs-rst: kernel-doc: fix typedef output in RST format · 82801d06
      由 Mauro Carvalho Chehab 提交于 
      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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      82801d06
    • M
      docs-rst: improve typedef parser · d37c43ce
      由 Mauro Carvalho Chehab 提交于 
      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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      d37c43ce
  17. 25 8月, 2016 1 次提交
    • M
      docs-rst: kernel-doc: better output struct members · 6d232c80
      由 Mauro Carvalho Chehab 提交于 
      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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      6d232c80
  19. 23 8月, 2016 1 次提交
  21. 23 7月, 2016 2 次提交
    • M
      doc-rst: kernel-doc: fix a change introduced by mistake · a3f57ad0
      由 Mauro Carvalho Chehab 提交于 
      changeset b7e67f6c ("doc-rst: linux_tv: supress lots of warnings")
were meant to touch only on media files, but it also touched
at this script by mistake. Revert such change.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
      a3f57ad0
    • M
      doc-rst: kernel-doc: fix handling of address_space tags · a88b1672
      由 Mauro Carvalho Chehab 提交于 
      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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>
      a88b1672
  23. 18 7月, 2016 1 次提交
  25. 04 7月, 2016 1 次提交
  27. 03 7月, 2016 1 次提交
    • M
      doc-rst: linux_tv: supress lots of warnings · b7e67f6c
      由 Mauro Carvalho Chehab 提交于 
      The c language parser checks if there are duplicated object
definitions. That causes lots of warnings like:
	WARNING: duplicate C object description of ioctl

Let's remove those by telling Sphinx that the language for
those objects are c++. The look of the descriptions will
be close, and the warnings will be gone.

Please notice that we had to keep a few of them as C, as
the c++ parser seems to be broken when it finds an enum.

Yet, this reduced from 219 warnings to 143, with is
a good thing.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
      b7e67f6c
  29. 10 6月, 2016 7 次提交
  31. 04 6月, 2016 1 次提交
    • D
      scripts/kernel-doc: Add option to inject line numbers · 0b0f5f29
      由 Daniel Vetter 提交于 
      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: NDaniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: NJani Nikula <jani.nikula@intel.com>
      0b0f5f29
  33. 03 6月, 2016 2 次提交
  35. 30 5月, 2016 8 次提交
    • J
      kernel-doc: reset contents and section harder · 2f4ad40a
      由 Jani Nikula 提交于 
      If the documentation comment does not have params or sections, the
section heading may leak from the previous documentation comment.
Signed-off-by: NJani Nikula <jani.nikula@intel.com>
      2f4ad40a
    • J
      kernel-doc: concatenate contents of colliding sections · 32217761
      由 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: NJani Nikula <jani.nikula@intel.com>
      32217761
    • J
      kernel-doc: limit the "section header:" detection to a select few · f624adef
      由 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: NJani Nikula <jani.nikula@intel.com>
      f624adef
    • J
      kernel-doc/rst: remove fixme comment · cddfe325
      由 Jani Nikula 提交于 
      Yes, for our purposes the type should contain typedef.
Signed-off-by: NJani Nikula <jani.nikula@intel.com>
      cddfe325
    • J
      kernel-doc/rst: use *undescribed* instead of _undescribed_ · d4b08e0c
      由 Jani Nikula 提交于 
      The latter isn't special to rst.
Signed-off-by: NJani Nikula <jani.nikula@intel.com>
      d4b08e0c
    • J
      kernel-doc: strip leading whitespace from continued param descs · b7886de4
      由 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: NJani Nikula <jani.nikula@intel.com>
      b7886de4
    • J
      kernel-doc: improve handling of whitespace on the first line param description · 0a726301
      由 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: NJani Nikula <jani.nikula@intel.com>
      0a726301
    • J
      kernel-doc/rst: change the output layout · ecbcfba1
      由 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: NJani Nikula <jani.nikula@intel.com>
      ecbcfba1