summaryrefslogtreecommitdiffstats
path: root/Documentation/doc-guide/kernel-doc.rst
Commit message (Collapse)AuthorAgeFilesLines
* Doc : doc-guide : Fix a typoSheriff Esseson2019-06-281-1/+1
| | | | | | | fix the disjunction by replacing "of" with "or". Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: kernel-doc: typo "if ... if" -> "if ... is"Frank Rowand2019-02-171-1/+1
| | | | | | | | | "If no *function* if specified" should instead be "If no *function* is specified". Reported-by: Matthew Wilcox <willy@infradead.org> Signed-off-by: Frank Rowand <frank.rowand@sony.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: kernel-doc: typo "documentaion"Frank Rowand2019-02-011-1/+1
| | | | | | | Fix a typo in kernel-doc.rst Signed-off-by: Frank Rowand <frank.rowand@sony.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: kernel-doc: update commands to generate man pageFrank Rowand2019-02-011-1/+14
| | | | | | | | | | | | | (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 <frank.rowand@sony.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* doc-guide:kernel-doc.rst: Reference to foobarJoris Gutjahr2018-11-071-1/+1
| | | | | | | | | | | | | | | 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 <joris.gutjahr@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* Documentation/sphinx: allow "functions" with no parametersMike Rapoport2018-06-301-2/+7
| | | | | | | | | | | | | | | | | | 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 <rppt@linux.vnet.ibm.com> Acked-by: Matthew Wilcox <willy@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* doc-guide: kernel-doc: add comment about formatting verificationMike Rapoport2018-02-231-0/+11
| | | | | | | | | 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 <rppt@linux.vnet.ibm.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* doc-guide: kernel-doc: add examples about nested union/structsMauro Carvalho Chehab2018-02-181-2/+11
| | | | | | | | 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 <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* doc-guide: kernel-doc: move in-line section to be after nested structMauro Carvalho Chehab2018-02-181-28/+28
| | | | | | | | | | | 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 <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* doc-guide: kernel-doc: fix example for inlined commentsMauro Carvalho Chehab2018-02-181-1/+1
| | | | | | | | 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 <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* doc-guide: kernel-doc: fix example for nested_foobar structMauro Carvalho Chehab2018-02-181-0/+4
| | | | | | | | | | | | | | | 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 <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* Restructure kernel-doc.rstMatthew Wilcox2018-02-131-259/+217
| | | | | | | | | | | | | | | | | | | | | | | | | | | | 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 <mawilcox@microsoft.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* Fix whitespace in exampleMatthew Wilcox2018-02-131-1/+1
| | | | | | | | Line up the second line in the way that the example purports to be showing. Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* Add scripts/split-man.plMatthew Wilcox2018-02-131-28/+2
| | | | | | | | | 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 <mawilcox@microsoft.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* Minor fixes to kernel-doc.rstMatthew Wilcox2018-02-131-8/+8
| | | | | | | | 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 <mawilcox@microsoft.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* Add documentation for Context sectionMatthew Wilcox2018-02-131-0/+25
| | | | | | | | | | | This section is mentioned in scripts/kernel-doc, so we should mention it in doc-guide/kernel-doc.rst. There are close to 500 comments using the Context section already, and almost 300 using a Locking section which fulfills much the same purpose (and should probably be converted for consistency). Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* scripts: kernel-doc: parse next structs/unionsMauro Carvalho Chehab2017-12-211-0/+46
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | There are several places within the Kernel tree with nested structs/unions, like this one: struct ingenic_cgu_clk_info { const char *name; enum { CGU_CLK_NONE = 0, CGU_CLK_EXT = BIT(0), CGU_CLK_PLL = BIT(1), CGU_CLK_GATE = BIT(2), CGU_CLK_MUX = BIT(3), CGU_CLK_MUX_GLITCHFREE = BIT(4), CGU_CLK_DIV = BIT(5), CGU_CLK_FIXDIV = BIT(6), CGU_CLK_CUSTOM = BIT(7), } type; int parents[4]; union { struct ingenic_cgu_pll_info pll; struct { struct ingenic_cgu_gate_info gate; struct ingenic_cgu_mux_info mux; struct ingenic_cgu_div_info div; struct ingenic_cgu_fixdiv_info fixdiv; }; struct ingenic_cgu_custom_info custom; }; }; Currently, such struct is documented as: **Definition** :: struct ingenic_cgu_clk_info { const char * name; }; **Members** ``name`` name of the clock With is obvioulsy wrong. It also generates an error: drivers/clk/ingenic/cgu.h:169: warning: No description found for parameter 'enum' However, there's nothing wrong with this kernel-doc markup: everything is documented there. It makes sense to document all fields there. So, add a way for the core to parse those structs. With this patch, all documented fields will properly generate documentation. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: kernel-doc.rst: add documentation about man pagesMauro Carvalho Chehab2017-12-211-0/+34
| | | | | | | | | kernel-doc-nano-HOWTO.txt has a chapter about man pages production. While we don't have a working "make manpages" target, add it. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: kernel-doc.rst: improve typedef documentationMauro Carvalho Chehab2017-12-211-10/+22
| | | | | | | | Add documentation about typedefs for function prototypes and move it to happen earlier. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: kernel-doc.rst: improve structs chapterMauro Carvalho Chehab2017-12-211-24/+24
| | | | | | | | | | | There is a mess on this chapter: it suggests that even enums and unions should be documented with "struct". That's not the way it should be ;-) Fix it and move it to happen earlier. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: kernel-doc.rst: improve function documentation sectionMauro Carvalho Chehab2017-12-211-39/+61
| | | | | | | | | Move its contents to happen earlier and improve the description of return values, adding a subsection to it. Most of the contents there came from kernel-doc-nano-HOWTO.txt. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: kernel-doc.rst: improve private members descriptionMauro Carvalho Chehab2017-12-211-26/+30
| | | | | | | | | The private members section can now be moved to be together with the arguments section. Move it there and add an example about the usage of public: Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: kernel-doc.rst: better describe kernel-doc argumentsMauro Carvalho Chehab2017-12-211-3/+41
| | | | | | | | | Add a new section to describe kernel-doc arguments, adding examples about how identation should happen, as failing to do that causes Sphinx to do the wrong thing. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* Documentation: fix ref to sphinx/kerneldoc.pyTom Saeger2017-10-191-1/+1
| | | | | Signed-off-by: Tom Saeger <tom.saeger@oracle.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* kernel-doc: describe the ``literal`` syntaxMauro Carvalho Chehab2017-05-161-0/+10
| | | | | | | | | | | | changeset b97f193abf83 ("scripts/kernel-doc: fix parser for apostrophes") added support for ``literal`` inside kernel-doc, in order to allow using the "%" symbol inside a literal block, as this is used at printk() description. Document it. Fixes: b97f193abf83 ("scripts/kernel-doc: fix parser for apostrophes") Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
* Merge branch 'mauro-doc' into docs-nextJonathan Corbet2016-11-191-1/+6
|
* docs-rst: doc-guide: split the kernel-documentation.rst contentsMauro Carvalho Chehab2016-11-191-0/+363
Having the kernel-documentation at the topmost level doesn't allow generating a separate PDF file for it. Also, makes harder to add extra contents. So, place it on a sub-dir. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
generated by cgit v1.2.3 (git 2.39.1) at 2024-05-26 09:23:04 +0000