kernel/linux.git/Documentation/doc-guide/kernel-doc.rst, branch v6.12.80

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

2024-05-30T19:35:07+00:00

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 Suggested-by: Dmitry Baryshkov Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240522224726.10498-1-rdunlap@infradead.org

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

2024-01-30T20:31:09+00:00

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 Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Acked-by: Daniel Vetter Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240107012400.32587-1-rdunlap@infradead.org

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

2023-07-14T19:16:59+00:00

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 Suggested-by: Steven Rostedt Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Link: https://lore.kernel.org/lkml/20221121154358.36856ca6@gandalf.local.home/ Acked-by: Steven Rostedt (Google) Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20230703232030.8223-1-rdunlap@infradead.org

docs: add Rust documentation

2022-09-28T07:02:45+00:00

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 Co-developed-by: Alex Gaynor Signed-off-by: Alex Gaynor Co-developed-by: Finn Behrens Signed-off-by: Finn Behrens Co-developed-by: Adam Bratschi-Kaye Signed-off-by: Adam Bratschi-Kaye Co-developed-by: Wedson Almeida Filho Signed-off-by: Wedson Almeida Filho Co-developed-by: Michael Ellerman Signed-off-by: Michael Ellerman Co-developed-by: Sven Van Asbroeck Signed-off-by: Sven Van Asbroeck Co-developed-by: Wu XiangCheng Signed-off-by: Wu XiangCheng Co-developed-by: Gary Guo Signed-off-by: Gary Guo Co-developed-by: Boris-Chengbiao Zhou Signed-off-by: Boris-Chengbiao Zhou Co-developed-by: Yuki Okushi Signed-off-by: Yuki Okushi Co-developed-by: Wei Liu Signed-off-by: Wei Liu Co-developed-by: Daniel Xu Signed-off-by: Daniel Xu Co-developed-by: Julian Merkle Signed-off-by: Julian Merkle Signed-off-by: Miguel Ojeda

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

2022-06-27T22:24:40+00:00

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 Link: https://lore.kernel.org/r/15636c13-7fa2-f973-6d3d-361222b839ef@gmail.com Signed-off-by: Jonathan Corbet

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

2022-04-05T16:00:43+00:00

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 Cc: "David S. Miller" Cc: Greg Kroah-Hartman Cc: Tony Nguyen Cc: Vinod Koul Cc: Daniel Borkmann Cc: Mauro Carvalho Chehab Cc: Akira Yokosawa Cc: "Rafael J. Wysocki" Cc: Jens Axboe Cc: linux-kernel@vger.kernel.org Signed-off-by: Bagas Sanjaya Signed-off-by: Jonathan Corbet

kernel-doc: Fix example in Nested structs/unions

2020-12-08T17:23:17+00:00

Add missing ';' as well as fixes the indent for the first struct. Signed-off-by: Ben Widawsky Link: https://lore.kernel.org/r/20201207210027.1049346-1-ben.widawsky@intel.com Signed-off-by: Jonathan Corbet

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

2020-10-15T05:49:38+00:00

Currently, there's no way to exclude identifiers from a kernel-doc markup. Add support for it. Signed-off-by: Mauro Carvalho Chehab

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

2020-09-03T19:50:40+00:00

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 Link: https://lore.kernel.org/r/20200903005747.3900333-3-nfraprado@protonmail.com Signed-off-by: Jonathan Corbet

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