kernel/linux
0
Fork 0
mirror of https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/ synced 2026-11-13 07:31:07 +00:00
Code Issues Releases Packages Activity
linux/Documentation/doc-guide/kernel-doc.rst

534 lines
17 KiB
Raw Permalink Normal View History

Documentation: add meta-documentation for Sphinx and kernel-doc Describe Sphinx, reStructuredText, the kernel-doc extension, the kernel-doc structured documentation comments, etc. The kernel-doc parts are based on kernel-doc-nano-HOWTO.txt, by Tim <twaugh@redhat.com>. Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-06-23 15:36:04 +03:00
Documentation: fix ref to sphinx/kerneldoc.py Signed-off-by: Tom Saeger <tom.saeger@oracle.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-10-12 15:23:42 -05:00
Documentation: add meta-documentation for Sphinx and kernel-doc Describe Sphinx, reStructuredText, the kernel-doc extension, the kernel-doc structured documentation comments, etc. The kernel-doc parts are based on kernel-doc-nano-HOWTO.txt, by Tim <twaugh@redhat.com>. Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-06-23 15:36:04 +03:00
Documentation/SubmitChecklist: update kernel-doc task Task 11 (kernel-doc) still mentions usage of make manpages, but this won't work if the API is documented via Sphinx. So, update it to use either htmldocs or pdfdocs, with are the documentation targets that work for all. While here, add ReST reference to the kernel documentation book. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-19 08:08:00 -03:00
Documentation: add meta-documentation for Sphinx and kernel-doc Describe Sphinx, reStructuredText, the kernel-doc extension, the kernel-doc structured documentation comments, etc. The kernel-doc parts are based on kernel-doc-nano-HOWTO.txt, by Tim <twaugh@redhat.com>. Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-06-23 15:36:04 +03:00
docs: kernel-doc.rst: better describe kernel-doc arguments 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>
2017-12-18 10:30:02 -02:00
Documentation: add meta-documentation for Sphinx and kernel-doc Describe Sphinx, reStructuredText, the kernel-doc extension, the kernel-doc structured documentation comments, etc. The kernel-doc parts are based on kernel-doc-nano-HOWTO.txt, by Tim <twaugh@redhat.com>. Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-06-23 15:36:04 +03:00
docs: kernel-doc.rst: better describe kernel-doc arguments 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>
2017-12-18 10:30:02 -02:00
Documentation: add meta-documentation for Sphinx and kernel-doc Describe Sphinx, reStructuredText, the kernel-doc extension, the kernel-doc structured documentation comments, etc. The kernel-doc parts are based on kernel-doc-nano-HOWTO.txt, by Tim <twaugh@redhat.com>. Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-06-23 15:36:04 +03:00
docs: kernel-doc.rst: better describe kernel-doc arguments 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>
2017-12-18 10:30:02 -02:00
Documentation: add meta-documentation for Sphinx and kernel-doc Describe Sphinx, reStructuredText, the kernel-doc extension, the kernel-doc structured documentation comments, etc. The kernel-doc parts are based on kernel-doc-nano-HOWTO.txt, by Tim <twaugh@redhat.com>. Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-06-23 15:36:04 +03:00
docs: kernel-doc.rst: better describe kernel-doc arguments 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>
2017-12-18 10:30:02 -02:00
docs: kernel-doc.rst: improve private members description 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>
2017-12-18 10:30:03 -02:00
docs: kernel-doc.rst: improve function documentation section 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>
2017-12-18 10:30:04 -02:00
docs: kernel-doc.rst: improve structs chapter 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>
2017-12-18 10:30:05 -02:00
scripts: kernel-doc: parse next structs/unions 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>
2017-12-18 10:30:13 -02:00
docs: kernel-doc.rst: improve structs chapter 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>
2017-12-18 10:30:05 -02:00
docs: kernel-doc.rst: improve typedef documentation 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>
2017-12-18 10:30:06 -02:00
docs: kernel-doc.rst: better describe kernel-doc arguments 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>
2017-12-18 10:30:02 -02:00
Documentation: add meta-documentation for Sphinx and kernel-doc Describe Sphinx, reStructuredText, the kernel-doc extension, the kernel-doc structured documentation comments, etc. The kernel-doc parts are based on kernel-doc-nano-HOWTO.txt, by Tim <twaugh@redhat.com>. Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-06-23 15:36:04 +03:00
kernel-doc: describe the ``literal`` syntax 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>
2017-05-16 08:17:49 -03:00
Documentation: add meta-documentation for Sphinx and kernel-doc Describe Sphinx, reStructuredText, the kernel-doc extension, the kernel-doc structured documentation comments, etc. The kernel-doc parts are based on kernel-doc-nano-HOWTO.txt, by Tim <twaugh@redhat.com>. Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-06-23 15:36:04 +03:00
doc: Document the new inline struct member kernel-doc style We don't just need better doc toolchains, we also need better docs for our doc toolchain! v2: Make sure we don't have foo twice (Jani). Cc: Daniel Vetter <daniel@ffwll.ch> Cc: Jani Nikula <jani.nikula@intel.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: linux-doc@vger.kernel.org Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-17 11:19:43 +01:00
Documentation: add meta-documentation for Sphinx and kernel-doc Describe Sphinx, reStructuredText, the kernel-doc extension, the kernel-doc structured documentation comments, etc. The kernel-doc parts are based on kernel-doc-nano-HOWTO.txt, by Tim <twaugh@redhat.com>. Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-06-23 15:36:04 +03:00
doc: Document the new inline struct member kernel-doc style We don't just need better doc toolchains, we also need better docs for our doc toolchain! v2: Make sure we don't have foo twice (Jani). Cc: Daniel Vetter <daniel@ffwll.ch> Cc: Jani Nikula <jani.nikula@intel.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: linux-doc@vger.kernel.org Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-17 11:19:43 +01:00
Documentation: add meta-documentation for Sphinx and kernel-doc Describe Sphinx, reStructuredText, the kernel-doc extension, the kernel-doc structured documentation comments, etc. The kernel-doc parts are based on kernel-doc-nano-HOWTO.txt, by Tim <twaugh@redhat.com>. Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-06-23 15:36:04 +03:00
docs: kernel-doc.rst: add documentation about man pages 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>
2017-12-18 10:30:07 -02:00