linux.git/Documentation/doc-guide/kernel-doc.rst, branch v4.19

Documentation/sphinx: allow "functions" with no parameters

2018-06-30T13:52:42+00:00

When kernel-doc:: specified in .rst document without explicit directives,
it outputs both comment and DOC: sections. If a DOC: section was explicitly
included in the same document it will be duplicated. For example, the
output generated for Documentation/core-api/idr.rst [1] has "IDA
description" in the "IDA usage" section and in the middle of the API
reference.

This patch enables using "functions" directive without parameters to output
all the documentation excluding DOC: sections.

[1] https://www.kernel.org/doc/html/v4.17/core-api/idr.html

Signed-off-by: Mike Rapoport 
Acked-by: Matthew Wilcox 
Signed-off-by: Jonathan Corbet

doc-guide: kernel-doc: add comment about formatting verification

2018-02-23T15:06:15+00:00

Currently there is no automated checking for kernel-doc comments except
running 'kernel-doc -v -none '. Mention the possibility to run
kernel-doc to verify formatting of the comments in the kernel-doc guide.

Signed-off-by: Mike Rapoport 
Signed-off-by: Jonathan Corbet

doc-guide: kernel-doc: add examples about nested union/structs

2018-02-18T23:55:10+00:00

It helps to give some examples about how to use in-line
comments also when nested union/structs are present. So add it.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet

doc-guide: kernel-doc: move in-line section to be after nested struct

2018-02-18T23:54:56+00:00

We want to give some examples about how to do in-line comments
for nested structs. So, move it to be after nested structs/unions
chapter.

The section content was not changed on this patch.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet

doc-guide: kernel-doc: fix example for inlined comments

2018-02-18T23:54:44+00:00

Without ending with a ";", kernel-doc doesn't recognize it
as an struct, and it fails to parse the example.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet

doc-guide: kernel-doc: fix example for nested_foobar struct

2018-02-18T23:54:34+00:00

There's a missing */ at the end of Kernel docs example.
Even adding it, it will still produce 3 warnings:

	example:33: warning: Function parameter or member 'bar' not described in 'nested_foobar'
	example:33: warning: Function parameter or member 'bar.st1' not described in 'nested_foobar'
	example:33: warning: Function parameter or member 'bar.st2' not described in 'nested_foobar'

So, make the example more complete and add the missing end
of comment there.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet

Restructure kernel-doc.rst

2018-02-13T21:22:01+00:00

I found the layout confusing with multiple introductions to what
kernel-doc is and how to use it.

I made the following changes:
 - Moved the 'Including kernel-doc comments' section to the end of
   the document -- we should explain what it *is* before we explain
   how to integrate it.
 - Moved the 'Recommendations' subsection to the top.  We want people
   to know what to document before telling them how to do it.
 - Rewrite the 'Writing kernel-doc comments' section, integrating
   the 'Recommendations' subsection and a paragraph from 'How to format
   kernel-doc comments'.
 - Remove the paragraph about the kernel-doc script; we're supposed to
   be teaching people how to use punctuation to write pretty documentation,
   not documenting the build tooling.
 - Split the 'Parameters and member arguments' section into 'Function
   parameters' and 'Members'.  Structure members are not commonly
   referred to as arguments.
 - Integrate the 'private:' and 'public:' tag descriptions into the
   'Members' section.
 - Move the 'In-line member documentation comments' subsection up to be
   with the 'Members' section.

Signed-off-by: Matthew Wilcox 
Signed-off-by: Jonathan Corbet

Fix whitespace in example

2018-02-13T21:21:57+00:00

Line up the second line in the way that the example purports to be
showing.

Signed-off-by: Matthew Wilcox 
Signed-off-by: Jonathan Corbet

Add scripts/split-man.pl

2018-02-13T21:21:52+00:00

Instead of asking the user to copy and paste a small perl script from
the documentation, just distribute the perl script in the scripts
directory.

Signed-off-by: Matthew Wilcox 
Signed-off-by: Jonathan Corbet

Minor fixes to kernel-doc.rst

2018-02-13T21:21:48+00:00

The author clearly meant to use the word 'which' here.  Also replace
some tabs with spaces which fixes the syntax highlighting in my editor.

Signed-off-by: Matthew Wilcox 
Signed-off-by: Jonathan Corbet