Documentation: kernel-doc: enumerate identifier *type*s

Explain that a kernel-doc :identifiers: line can refer to a struct,
union, enum, or typedef as well as functions.

Signed-off-by: Randy Dunlap

Documentation: kernel-doc: enumerate identifier *type*s

Explain that a kernel-doc :identifiers: line can refer to a struct,
union, enum, or typedef as well as functions.

Signed-off-by: Randy Dunlap <[email protected]>
Cc: Jonathan Corbet <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

doc-guide: kernel-doc: document Returns: spelling

scripts/kernel-doc accepts "Return:" or "Returns:" for describing the
return value of a function or function-like macro, so document this
alternativ

doc-guide: kernel-doc: document Returns: spelling

scripts/kernel-doc accepts "Return:" or "Returns:" for describing the
return value of a function or function-like macro, so document this
alternative spelling and use it in an example.

Signed-off-by: Randy Dunlap <[email protected]>
Suggested-by: Dmitry Baryshkov <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

doc-guide: kernel-doc: tell about object-like macros

Since 2014 kernel-doc has supported describing object-like macros
but it is not documented anywhere. I should have required some
documentation fo

doc-guide: kernel-doc: tell about object-like macros

Since 2014 kernel-doc has supported describing object-like macros
but it is not documented anywhere. I should have required some
documentation for it when I merged the patch. :(

There are currently only 3 uses of this (all in DRM headers, in
include/drm/*.h).

Add object-like macro kernel-doc documentation now so that more may
know about it and use it.

Fixes: cbb4d3e6510b ("scripts/kernel-doc: handle object-like macros")
Signed-off-by: Randy Dunlap <[email protected]>
Cc: Jonathan Corbet <[email protected]>
Cc: [email protected]
Acked-by: Daniel Vetter <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

Documentation: doc-guide: use '%' constant indicator in Return: examples

Use the 'constant' indicator '%' in the examples for the
Return: values syntax. This can help encourage people to use it.

Si

Documentation: doc-guide: use '%' constant indicator in Return: examples

Use the 'constant' indicator '%' in the examples for the
Return: values syntax. This can help encourage people to use it.

Signed-off-by: Randy Dunlap <[email protected]>
Suggested-by: Steven Rostedt <[email protected]>
Cc: Jonathan Corbet <[email protected]>
Cc: [email protected]
Link: https://lore.kernel.org/lkml/[email protected]/
Acked-by: Steven Rostedt (Google) <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

docs: add Rust documentation

Most of the documentation for Rust is written within the source code
itself, as it is idiomatic for Rust projects. This applies to both
the shared infrastructure at `rus

docs: add Rust documentation

Most of the documentation for Rust is written within the source code
itself, as it is idiomatic for Rust projects. This applies to both
the shared infrastructure at `rust/` as well as any other Rust module
(e.g. drivers) written across the kernel.

However, these documents contain general information that does not
fit particularly well in the source code, like the Quick Start guide.

It also contains a few other small changes elsewhere in the
documentation folder.

Reviewed-by: Kees Cook <[email protected]>
Co-developed-by: Alex Gaynor <[email protected]>
Signed-off-by: Alex Gaynor <[email protected]>
Co-developed-by: Finn Behrens <[email protected]>
Signed-off-by: Finn Behrens <[email protected]>
Co-developed-by: Adam Bratschi-Kaye <[email protected]>
Signed-off-by: Adam Bratschi-Kaye <[email protected]>
Co-developed-by: Wedson Almeida Filho <[email protected]>
Signed-off-by: Wedson Almeida Filho <[email protected]>
Co-developed-by: Michael Ellerman <[email protected]>
Signed-off-by: Michael Ellerman <[email protected]>
Co-developed-by: Sven Van Asbroeck <[email protected]>
Signed-off-by: Sven Van Asbroeck <[email protected]>
Co-developed-by: Wu XiangCheng <[email protected]>
Signed-off-by: Wu XiangCheng <[email protected]>
Co-developed-by: Gary Guo <[email protected]>
Signed-off-by: Gary Guo <[email protected]>
Co-developed-by: Boris-Chengbiao Zhou <[email protected]>
Signed-off-by: Boris-Chengbiao Zhou <[email protected]>
Co-developed-by: Yuki Okushi <[email protected]>
Signed-off-by: Yuki Okushi <[email protected]>
Co-developed-by: Wei Liu <[email protected]>
Signed-off-by: Wei Liu <[email protected]>
Co-developed-by: Daniel Xu <[email protected]>
Signed-off-by: Daniel Xu <[email protected]>
Co-developed-by: Julian Merkle <[email protected]>
Signed-off-by: Julian Merkle <[email protected]>
Signed-off-by: Miguel Ojeda <[email protected]>

show more ...

docs/doc-guide: Put meta title for kernel-doc HTML page

kernel-doc.rst has two 1st level section titles of "Writing
kernel-doc comments" and "Including kernel-doc comments".

Therefore, rather than

docs/doc-guide: Put meta title for kernel-doc HTML page

kernel-doc.rst has two 1st level section titles of "Writing
kernel-doc comments" and "Including kernel-doc comments".

Therefore, rather than using the first one, put a meta title
of "Kernel-doc comments" for the title of the resulting HTML
page by using the "title" directive.

Signed-off-by: Akira Yokosawa <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

Documentation: kernel-doc: Promote two chapter headings to page title

Promote "Writing kernel-doc comments" heading to page title, in
accordance to kernel documentation guidelines. Also promote "Inc

Documentation: kernel-doc: Promote two chapter headings to page title

Promote "Writing kernel-doc comments" heading to page title, in
accordance to kernel documentation guidelines. Also promote "Including
kernel-doc comments" heading because both headings deserve their own
chapters in PDF output.

There is no differences in the resulting output except formatting
semantics.

Cc: Jonathan Corbet <[email protected]>
Cc: "David S. Miller" <[email protected]>
Cc: Greg Kroah-Hartman <[email protected]>
Cc: Tony Nguyen <[email protected]>
Cc: Vinod Koul <[email protected]>
Cc: Daniel Borkmann <[email protected]>
Cc: Mauro Carvalho Chehab <[email protected]>
Cc: Akira Yokosawa <[email protected]>
Cc: "Rafael J. Wysocki" <[email protected]>
Cc: Jens Axboe <[email protected]>
Cc: [email protected]
Signed-off-by: Bagas Sanjaya <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

kernel-doc: Fix example in Nested structs/unions

Add missing ';' as well as fixes the indent for the first struct.

Signed-off-by: Ben Widawsky <[email protected]>
Link: https://lore.kernel.org

kernel-doc: Fix example in Nested structs/unions

Add missing ';' as well as fixes the indent for the first struct.

Signed-off-by: Ben Widawsky <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: kerneldoc.py: add support for kerneldoc -nosymbol

Currently, there's no way to exclude identifiers from
a kernel-doc markup. Add support for it.

Signed-off-by: Mauro Carvalho Chehab <mchehab+

docs: kerneldoc.py: add support for kerneldoc -nosymbol

Currently, there's no way to exclude identifiers from
a kernel-doc markup. Add support for it.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>

show more ...

kernel-doc: Update "cross-referencing from rST" section to use automarkup

Update text and examples in the "Cross-referencing from
reStructuredText" section to reflect that no additional syntax is ne

kernel-doc: Update "cross-referencing from rST" section to use automarkup

Update text and examples in the "Cross-referencing from
reStructuredText" section to reflect that no additional syntax is needed
anymore.

Signed-off-by: Nícolas F. R. A. Prado <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

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

The 'functions' directive is not only for functions, but also works for
structs/unions. So the name is misleading. This patch

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

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 <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

Doc : doc-guide : Fix a typo

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

Signed-off-by: Sheriff Esseson <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

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

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

Reported-by: Matthew Wilcox <[email protected]>
Signed-off-by:

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

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

Reported-by: Matthew Wilcox <[email protected]>
Signed-off-by: Frank Rowand <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: kernel-doc: typo "documentaion"

Fix a typo in kernel-doc.rst

Signed-off-by: Frank Rowand <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

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

(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

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

(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 <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

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

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.

B

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

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 <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

Documentation/sphinx: allow "functions" with no parameters

When kernel-doc:: specified in .rst document without explicit directives,
it outputs both comment and DOC: sections. If a DOC: section was

Documentation/sphinx: allow "functions" with no parameters

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 <[email protected]>
Acked-by: Matthew Wilcox <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

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

Currently there is no automated checking for kernel-doc comments except
running 'kernel-doc -v -none <filename>'. Mention the possibi

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

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

Signed-off-by: Mike Rapoport <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

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

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:

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

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 <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

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

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

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

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 <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

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

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 Che

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

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 <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

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

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

example:33: warning: Function

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

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 <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

Restructure kernel-doc.rst

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 comment

Restructure kernel-doc.rst

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 <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

Fix whitespace in example

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

Signed-off-by: Matthew Wilcox <[email protected]>
Signed-off-by: Jonathan Corbet <corbet@l

Fix whitespace in example

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

Signed-off-by: Matthew Wilcox <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

Add scripts/split-man.pl

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 Wi

Add scripts/split-man.pl

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 <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...