linux.git/Documentation/doc-guide/kernel-doc.rst, branch v5.7

kernel-doc: rename the kernel-doc directive 'functions' to 'identifiers'

2019-11-07T20:17:25+00:00

The 'functions' directive is not only for functions, but also works for
structs/unions. So the name is misleading. This patch renames it to
'identifiers', which specific the functions/types to be included in
documentation. We keep the old name as an alias of the new one before
all documentation are updated.

Signed-off-by: Changbin Du 
Signed-off-by: Jonathan Corbet

Doc : doc-guide : Fix a typo

2019-06-28T15:04:14+00:00

fix the disjunction by replacing "of" with "or".

Signed-off-by: Sheriff Esseson 
Signed-off-by: Jonathan Corbet

docs: kernel-doc: typo "if ... if" -> "if ... is"

2019-02-17T22:38:47+00:00

"If no *function* if specified" should instead be
"If no *function* is specified".

Reported-by: Matthew Wilcox 
Signed-off-by: Frank Rowand 
Signed-off-by: Jonathan Corbet

docs: kernel-doc: typo "documentaion"

2019-02-01T22:59:46+00:00

Fix a typo in kernel-doc.rst

Signed-off-by: Frank Rowand 
Signed-off-by: Jonathan Corbet

docs: kernel-doc: update commands to generate man page

2019-02-01T22:59:02+00:00

(1) The command to generate man pages is truncated in the pdf version
of the document.  Reformat the command into multiple lines to prevent
the truncation.

(2) Older versions of git do not support all variants of pathspec
syntax.  Provide commands to generate man pages for various
alternate syntax.

Signed-off-by: Frank Rowand 
Signed-off-by: Jonathan Corbet

doc-guide:kernel-doc.rst: Reference to foobar

2018-11-07T22:31:51+00:00

In the Function documentation Section of kernel-doc.rst
there is a function_name() function as an example for
how to make a comment about a function.

But at the end of that example there is a reference to foobar
instead of function_name.

I think that should rather be function_name, because that
was the placeholder the whole example was using.

Signed-off-by: Joris Gutjahr 
Signed-off-by: Jonathan Corbet

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