From: "Heiser, Markus" <markus.heiser@xxxxxxxxxxx> The kernel-doc-HOWTO book is a rewrite of the kernel-doc-nano-HOWTO.txt, taking reST extension into account. The kernel-doc-HOWTO is a user guide for kernel developers that also serves as a specification. The format for this documentation is called the *kernel-doc* format. With kernel version 4.x the restructuredText (reST_) markup was added to the *kernel-doc* format. The kernel-doc parser supports the markup modes: * kernel-doc (vintage) * reST This document gives hints on how to use these markups and how to refer and extract documentation from source files. A online kernel-doc-HOWTO is available at [1] [1] http://return42.github.io/sphkerneldoc/books/kernel-doc-HOWTO Signed-off-by: Markus Heiser <markus.heiser@xxxxxxxxxxx> --- Documentation/books/kernel-doc-HOWTO.conf | 200 +++++++++ .../books/kernel-doc-HOWTO/all-in-a-tumble-src.rst | 12 + .../books/kernel-doc-HOWTO/all-in-a-tumble.h | 271 +++++++++++ .../books/kernel-doc-HOWTO/all-in-a-tumble.rst | 11 + Documentation/books/kernel-doc-HOWTO/csv_table.txt | 6 + Documentation/books/kernel-doc-HOWTO/index.rst | 46 ++ .../kernel-doc-HOWTO/kernel-doc-components.rst | 35 ++ .../kernel-doc-HOWTO/kernel-doc-directive.rst | 199 ++++++++ .../books/kernel-doc-HOWTO/kernel-doc-examples.rst | 16 + .../books/kernel-doc-HOWTO/kernel-doc-intro.rst | 85 ++++ .../books/kernel-doc-HOWTO/kernel-doc-syntax.rst | 171 +++++++ .../kernel-doc-HOWTO/reST-kernel-doc-mode.rst | 120 +++++ Documentation/books/kernel-doc-HOWTO/refs.txt | 15 + .../books/kernel-doc-HOWTO/table-markup.rst | 499 +++++++++++++++++++++ .../books/kernel-doc-HOWTO/test/parser_test.h | 332 ++++++++++++++ .../kernel-doc-HOWTO/vintage-kernel-doc-mode.rst | 100 +++++ 16 files changed, 2118 insertions(+) create mode 100644 Documentation/books/kernel-doc-HOWTO.conf create mode 100644 Documentation/books/kernel-doc-HOWTO/all-in-a-tumble-src.rst create mode 100644 Documentation/books/kernel-doc-HOWTO/all-in-a-tumble.h create mode 100644 Documentation/books/kernel-doc-HOWTO/all-in-a-tumble.rst create mode 100644 Documentation/books/kernel-doc-HOWTO/csv_table.txt create mode 100644 Documentation/books/kernel-doc-HOWTO/index.rst create mode 100644 Documentation/books/kernel-doc-HOWTO/kernel-doc-components.rst create mode 100644 Documentation/books/kernel-doc-HOWTO/kernel-doc-directive.rst create mode 100644 Documentation/books/kernel-doc-HOWTO/kernel-doc-examples.rst create mode 100644 Documentation/books/kernel-doc-HOWTO/kernel-doc-intro.rst create mode 100644 Documentation/books/kernel-doc-HOWTO/kernel-doc-syntax.rst create mode 100644 Documentation/books/kernel-doc-HOWTO/reST-kernel-doc-mode.rst create mode 100644 Documentation/books/kernel-doc-HOWTO/refs.txt create mode 100644 Documentation/books/kernel-doc-HOWTO/table-markup.rst create mode 100644 Documentation/books/kernel-doc-HOWTO/test/parser_test.h create mode 100644 Documentation/books/kernel-doc-HOWTO/vintage-kernel-doc-mode.rst diff --git a/Documentation/books/kernel-doc-HOWTO.conf b/Documentation/books/kernel-doc-HOWTO.conf new file mode 100644 index 0000000..4e8c32a --- /dev/null +++ b/Documentation/books/kernel-doc-HOWTO.conf @@ -0,0 +1,200 @@ +# -*- coding: utf-8; mode: python -*- +# +# This is the project specific sphinx-build configuration, which is loaded from +# the base configuration file (``../conf.py``). About config values consult: +# +# * http://www.sphinx-doc.org/en/stable/config.html +# +# While setting values here, please take care to not overwrite common needed +# configurations. This means, do not *overwrite* composite values (e.g. the +# list- or dictionary-value of "latex_elements" resp. "extensions") by +# thoughtless assignments. Manipulate composite values always by *update* +# (dict-values) or extend (list-values). Nevertheless, if you know what you are +# doing, you are free to *overwrite* values to your needs. +# +# useful preseted names: +# +# * BASE_FOLDER: the folder where the top conf.py is located +# * main_name: the basename of this project-folder + +# ------------------------------------------------------------------------------ +# General configuration +# ------------------------------------------------------------------------------ + +project = u'kernel-doc HOWTO' +copyright = u'2016, Linux documentation authors' +author = u'Linux contributors' + +extlinks.update({ }) + +intersphinx_mapping.update({ }) + +extensions.extend([ + # 'sphinx.ext.pngmath' + #, 'sphinx.ext.mathjax' +]) + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = u'1.0' +# The full version, including alpha/beta/rc tags. +# release = u'0' + +# ------------------------------------------------------------------------------ +# Options for HTML output +# ------------------------------------------------------------------------------ + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = pathjoin(BASE_FOLDER, "_tex", "logo.png") + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path.extend([]) + +# Output file base name for HTML help builder. +htmlhelp_basename = main_name + +# ------------------------------------------------------------------------------ +# Options for XeLaTeX output +# ------------------------------------------------------------------------------ + +xelatex_documents = [ + # A book with default DIN A4 and 12pt + dict(docname = master_doc + , targetname = "%s.tex" % main_name + , documentclass = "darmarITArticle")] + +# This value determines the topmost sectioning unit. It should be chosen from +# ``part``, ``chapter`` or ``section``. The default is ``None``; the topmost +# sectioning unit is switched by documentclass. ``section`` is used if +# documentclass will be ``howto``, otherwise ``chapter`` will be used. + +latex_toplevel_sectioning = 'chapter' + +# ------------------------------------------------------------------------------ +# Options for manual page output +# ------------------------------------------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +# man_pages = [ +# (master_doc, 'kernel-doc', u'Kernel-Doc', +# [author], 1) +# ] + +# If true, show URL addresses after external links. +#man_show_urls = False + +# ------------------------------------------------------------------------------ +# Options for Texinfo output +# ------------------------------------------------------------------------------ + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +# texinfo_documents = [ +# (master_doc, 'Kernel-Doc', u'Kernel-Doc Documentation', +# author, 'Kernel-Doc', 'One line description of project.', +# 'Miscellaneous'), +# ] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False + +# ------------------------------------------------------------------------------ +# Options for Epub output +# ------------------------------------------------------------------------------ + +# Bibliographic Dublin Core info. +# epub_title = project +# epub_author = author +# epub_publisher = author +# epub_copyright = copyright + +# The basename for the epub file. It defaults to the project name. +#epub_basename = project + +# The HTML theme for the epub output. Since the default themes are not +# optimized for small screen space, using the same theme for HTML and epub +# output is usually not wise. This defaults to 'epub', a theme designed to save +# visual space. +#epub_theme = 'epub' + +# The language of the text. It defaults to the language option +# or 'en' if the language is not set. +#epub_language = '' + +# The scheme of the identifier. Typical schemes are ISBN or URL. +#epub_scheme = '' + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +#epub_identifier = '' + +# A unique identification for the text. +#epub_uid = '' + +# A tuple containing the cover image and cover page html template filenames. +#epub_cover = () + +# A sequence of (type, uri, title) tuples for the guide element of content.opf. +#epub_guide = () + +# HTML files that should be inserted before the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_pre_files.extend([]) + +# HTML files that should be inserted after the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_post_files.extend([]) + +# A list of files that should not be packed into the epub file. +epub_exclude_files.extend([]) + +# The depth of the table of contents in toc.ncx. +#epub_tocdepth = 3 + +# Allow duplicate toc entries. +#epub_tocdup = True + +# Choose between 'default' and 'includehidden'. +#epub_tocscope = 'default' + +# Fix unsupported image types using the Pillow. +#epub_fix_images = False + +# Scale large images. +#epub_max_image_width = 0 + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#epub_show_urls = 'inline' + +# If false, no index is generated. +#epub_use_index = True + diff --git a/Documentation/books/kernel-doc-HOWTO/all-in-a-tumble-src.rst b/Documentation/books/kernel-doc-HOWTO/all-in-a-tumble-src.rst new file mode 100644 index 0000000..9d360ae --- /dev/null +++ b/Documentation/books/kernel-doc-HOWTO/all-in-a-tumble-src.rst @@ -0,0 +1,12 @@ +.. -*- coding: utf-8; mode: rst -*- +.. include:: refs.txt + +.. _all-in-a-tumble-src: + +================ +Examples Sources +================ + +.. literalinclude:: ./all-in-a-tumble.h + :linenos: + :language: c diff --git a/Documentation/books/kernel-doc-HOWTO/all-in-a-tumble.h b/Documentation/books/kernel-doc-HOWTO/all-in-a-tumble.h new file mode 100644 index 0000000..d72c8bd --- /dev/null +++ b/Documentation/books/kernel-doc-HOWTO/all-in-a-tumble.h @@ -0,0 +1,271 @@ +/* parse-markup: reST */ + +/* parse-SNIP: intro */ +/** + * DOC: kernel-doc intro + * + * This file / chapter includes all the refered examples of the kernel-doc-HOWTO + * and additional tests. + * + * The content itself is nonsens / don’t look to close ;-) + */ +/* parse-SNAP: */ + + +/* parse-SNIP: hello-world */ +#include<stdio.h> +int main() { + printf("Hello World\n"); + return 0; +} +/* parse-SNAP: */ + + +/* parse-SNIP: my_struct */ +/** + * struct my_struct - short description + * @a: first member + * @b: second member + * + * Longer description + */ +struct my_struct { + int a; + int b; +/* private: */ + int c; +}; +/* parse-SNAP: */ + + +/* parse-SNIP: my_long_struct */ +/** + * struct my_struct - short description + * @a: first member + * @b: second member + * + * Longer description + */ +struct my_long_struct { + int a; + int b; + /** + * @c: This is longer description of C. + * + * You can use paragraphs to describe arguments + * using this method. + */ + int c; +}; +/* parse-SNAP: */ + + +/* parse-SNIP: theory-of-operation */ +/** + * DOC: Theory of Operation + * + * The whizbang foobar is a dilly of a gizmo. It can do whatever you + * want it to do, at any time. It reads your mind. Here's how it works. + * + * foo bar splat + * + * The only drawback to this gizmo is that is can sometimes damage + * hardware, software, or its subject(s). + */ +/* parse-SNAP: */ + + + +/* parse-SNIP: user_function */ +/** + * user_function - function that can only be called in user context + * @a: some argument + * Context: !in_interrupt() + * + * This function makes no sense, it is only kernel-doc demonstration. + * + * :: + * + * Example: + * x = user_function(22); + * + * Return: + * Returns first argument + */ +int user_function(int a) +{ + return a; +} +/* parse-SNAP: */ + + + + +/* parse-markup: kernel-doc */ + +/** + * vintage - short description of this function + * @parameter_a: first argument + * @parameter_b: second argument + * Context: in_gizmo_mode(). + * + * Long description. This function has two integer arguments. The first is + * @parameter_a and the second is @parameter_b. + * + * Example: + * user_function(22); + * + * Return: + * Sum of @parameter_a and @parameter_b. + * + * highlighting: + * + * - vintage() : function + * - @parameter_a : name of a parameter + * - $ENVVAR : environmental variable + * - &my_struct : name of a structure (up to two words including ``struct``) + * - %CONST : name of a constant. + * + * Parser Mode: *vintage* kernel-doc mode + * + * Within the *vintage kernel-doc mode* dogged ignores any whitespace or inline + * markup. + * + * - Inline markup like *emphasis* or **emphasis strong** + * - Literals and/or block indent: + * + * a + b + * + * In kernel-doc *vintage* mode, there are no special block or inline markups + * available. Markups like the one above result in ambiguous reST markup which + * could produce error messages in the subsequently sphinx-build + * process. Unexpected outputs are mostly the result. + * + * This is a link https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/ + * to the Linux kernel source tree + * + * colon markup: sectioning by colon markup in vintage mode is partial ugly. ;-) + * + */ +int vintage(int parameter_a, char parameter_b) +{ + return a + b; +} + + +/* parse-markup: reST */ + +/** + * rst_mode - short description of this function + * @a: first argument + * @b: second argument + * Context: :c:func:`in_gizmo_mode`. + * + * Long description. This function has two integer arguments. The first is + * ``parameter_a`` and the second is ``parameter_b``. + * + * As long as the reST / sphinx-doc toolchain uses `intersphinx + * <http://www.sphinx-doc.org/en/stable/ext/intersphinx.html>`__ you can refer + * definitions *outside* like :c:type:`struct media_device <media_device>`. If + * the description of ``media_device`` struct is found in any of the intersphinx + * locations, a hyperref to this target is genarated a build time. + * + * Example: + * + * .. code-block:: c + * + * user_function(22); + * + * Return: + * Sum of ``parameter_a`` and the second is ``parameter_b``. + * + * highlighting: + * + * Because reST markup syntax conflicts with the highlighting markup from the + * *vintage* mode, these *vintage* highlighting markup is not available in + * reST-mode. reST brings it's own markup to refer and highlight function, + * structs or whatever definition : + * + * - :c:func:`rst_mode` : function + * - ``$ENVVAR``: environmental variable + * - :c:type:`my_struct` : name of a structure + * - ``parameter_a`` : name of a parameter + * - ``CONST`` : name of a constant. + * + * Parser Mode: + * + * This is an example with activated reST additions, in this section you will + * find some common inline markups. + * + * Within the *reST mode* the kernel-doc parser pass through all markups to the + * reST toolchain, except the *vintage highlighting* but including any + * whitespace. With this, the full reST markup is available in the comments. + * + * This is a link to the `Linux kernel source tree + * <https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/>`_. + * + * This description is only to show some reST inline markups like *emphasise* + * and **emphasis strong**. The follwing is a demo of a reST list markup: + * + * Definition list: + * :def1: lorem + * :def2: ipsum + * + * Ordered List: + * - item one + * - item two + * - item three with + * a linebreak + * + * Literal blocks: + * The next example shows a literal block:: + * + * +------+ +------+ + * |\ |\ /| /| + * | +----+-+ +-+----+ | + * | | | | | | | | + * +-+----+ | | +----+-+ + * \| \| |/ |/ + * +------+ +------+ + * + * Highlighted code blocks: + * The next example shows a code example, with highlighting C syntax in the + * output. + * + * .. code-block:: c + * + * // Hello World program + * + * #include<stdio.h> + * + * int main() + * { + * printf("Hello World"); + * } + * + * + * reST sectioning: + * + * colon markup: sectioning by colon markup in reST mode is less ugly. ;-) + * + * A kernel-doc section like *this* section is translated into a reST + * *subsection*. This means, you can only use the follwing *sub-levels* within a + * kernel-doc section. + * + * a subsubsection + * ^^^^^^^^^^^^^^^ + * + * lorem ipsum + * + * a paragraph + * """"""""""" + * + * lorem ipsum + * + */ + +int rst_mode(int a, char b) +{ + return a + b; +} + diff --git a/Documentation/books/kernel-doc-HOWTO/all-in-a-tumble.rst b/Documentation/books/kernel-doc-HOWTO/all-in-a-tumble.rst new file mode 100644 index 0000000..17b127b --- /dev/null +++ b/Documentation/books/kernel-doc-HOWTO/all-in-a-tumble.rst @@ -0,0 +1,11 @@ +.. -*- coding: utf-8; mode: rst -*- +.. include:: refs.txt + +.. _all-in-a-tumble: + +================= +Rendered Examples +================= + +.. kernel-doc:: ./all-in-a-tumble.h + :module: example diff --git a/Documentation/books/kernel-doc-HOWTO/csv_table.txt b/Documentation/books/kernel-doc-HOWTO/csv_table.txt new file mode 100644 index 0000000..8a14541 --- /dev/null +++ b/Documentation/books/kernel-doc-HOWTO/csv_table.txt @@ -0,0 +1,6 @@ +stub col row 1, column, "loremLorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy +eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam +voluptua." +stub col row 1, "At vero eos et accusam et justo duo dolores et ea rebum. Stet clita +kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.", column +stub col row 1, column, column diff --git a/Documentation/books/kernel-doc-HOWTO/index.rst b/Documentation/books/kernel-doc-HOWTO/index.rst new file mode 100644 index 0000000..1893303 --- /dev/null +++ b/Documentation/books/kernel-doc-HOWTO/index.rst @@ -0,0 +1,46 @@ +.. -*- coding: utf-8; mode: rst -*- +.. include:: refs.txt + +.. _kernel-doc-howto: + +================ +kernel-doc HOWTO +================ + +In order to provide embedded, 'C' friendly, easy to maintain, but consistent and +extractable documentation of the functions and data structures in the Linux +kernel, the Linux kernel has adopted a consistent style for documenting +functions and their parameters, and structures and their members. + +The format for this documentation is called the *kernel-doc* format. With kernel +version 4.x the restructuredText (reST_) markup was added to the *kernel-doc* +format. The kernel-doc parser supports the markup modes: +:ref:`vintage-kernel-doc-mode` / :ref:`reST-kernel-doc-mode`. This document +gives hints on how to use these markups and how to refer and extract +documentation from source files. + +The kernel-doc parser extracts the kernel-doc descriptions from the source files +and produced reST markup as base format. With reST as base format the +documentation building process changed also. The building process is now based +on sphinx-doc_ and the DocBook documents will be migrated to reST gradually. + +.. toctree:: + :maxdepth: 1 + + kernel-doc-intro + kernel-doc-syntax + vintage-kernel-doc-mode + reST-kernel-doc-mode + kernel-doc-directive + table-markup + kernel-doc-components + kernel-doc-examples + +The examples in this HOWTO using the kernel-doc comments from the example file +:ref:`all-in-a-tumble-src`. They are rendered in the +chapter :ref:`all-in-a-tumble`. + +.. only:: html + + * :ref:`genindex` + diff --git a/Documentation/books/kernel-doc-HOWTO/kernel-doc-components.rst b/Documentation/books/kernel-doc-HOWTO/kernel-doc-components.rst new file mode 100644 index 0000000..f515f04 --- /dev/null +++ b/Documentation/books/kernel-doc-HOWTO/kernel-doc-components.rst @@ -0,0 +1,35 @@ +.. -*- coding: utf-8; mode: rst -*- +.. include:: refs.txt + +.. _kernel-doc-components: + +=================================== +Components of the kernel-doc system +=================================== + +Many places in the source tree have extractable kernel-doc documentation. The +components of this system are: + +Documentation/Makefile.reST and Documentation/conf.py + Makefile and basic `sphinx config`_ file to build the various reST documents + and output formats. Provides the basic sphinx-doc_ build infrastructure + including the *sphinx-subprojects* feature. With this feature each book can be + build and distributed stand-alone. Cross reference between *subprojects* will + be ensured by `intersphinx`_. + +Documentation/sphinx-static and Documentation/sphinx-tex + Paths that contain sphinx-doc_ custom static files (such as style sheets). + +Documentation/books + In this folder, the books with reST markup are placed. To provide + *sphinx-subprojects*, each book has its one folder and a (optional) + ``Documentation/books/{book-name}.conf`` file which *overwrites* the basic + configuration from ``Documentation/conf.py`` (settings see `sphinx config`_) + +scripts/site-python/linuxdoc + This folder includes python extensions related to the linux documentation + processes. + + + + diff --git a/Documentation/books/kernel-doc-HOWTO/kernel-doc-directive.rst b/Documentation/books/kernel-doc-HOWTO/kernel-doc-directive.rst new file mode 100644 index 0000000..5ae5c76 --- /dev/null +++ b/Documentation/books/kernel-doc-HOWTO/kernel-doc-directive.rst @@ -0,0 +1,199 @@ +.. -*- coding: utf-8; mode: rst -*- +.. include:: refs.txt + +.. _kernel-doc-directive: + +================================ +Use kernel-doc in reST documents +================================ + +There exists a `reST-directive +<http://www.sphinx-doc.org/en/stable/rest.html#directives>`_ named +``kernel-doc`` to integrate kernel-doc comments into a reST document (e.g. in a +*book*). The directive comes with options to fine grain control which parts +should be placed into the reST document. With no options given, the complete +kernel-doc comments from a source file will be inserted. So, the first and very +simple example is: + +.. code-block:: rst + + My Media Book + ============= + + .. kernel-doc:: include/media/media-device.h + +With this small example the kernel-doc comments from the media-device.h will be +inserted direct under the chapter "My Media Book". The "DOC:" sections, the function +and the type descriptions will be inserted in the order they appear in the source file. +Mostly you want to select more fine grained, read on to see how. + +kernel-doc config +================= + +Within the sphinx-doc config file (``config.py``) you can set the following +option. + +kernel_doc_raise_error: ``True`` + If true, fatal errors (like missing function descriptions) raise an error. The + default is ``True``. Because this might break your build process, you can + change the value to ``False``. + + In this example, the documentation of definition ``no_longer_exists`` is + required. + + .. code-block:: rst + + .. kernel-doc:: ./all-in-a-tumble.h + :functions: no_longer_exist + + Since this definition not exists (anymore), the following TODO entry is + inserted, when ``kernel_doc_raise_error`` is ``False``. + + .. kernel-doc:: ./all-in-a-tumble.h + :functions: no_longer_exist + + +kernel-doc options +================== + +Here is a short overview of the options: + +.. code-block:: rst + + .. kernel-doc:: <filename> + :doc: <section title> + :export: + :internal: + :functions: <function [, functions [, ...]]> + :module: <prefix-id> + :snippets: <snippet [, snippets [, ...]]> + :language: <snippet-lang> + :linenos: + :debug: + +The argument ``<filename>`` is required, it points to a source file in the +kernel source tree. The pathname is relativ to kernel's root folder. The +options have the following meaning, but be aware that not all combinations of +these options make sense: + +``doc <section title>`` + Inserts the contents of the ``DOC:`` section titled ``<section title>``. + Spaces are allowed in ``<section title>``; do not quote the ``<section + title>``. + +``export`` + Inserts the documentation of function, struct or whatever definition that is + exported using EXPORT_SYMBOL (``EXPORT_SYMBOL()``, ``EXPORT_SYMBOL_GPL()`` & + ``EXPORT_SYMBOL_GPL_FUTURE()``). Assume that a the all exported symbols are + documented. + +``internal`` + Inserts the documentation of function, struct or whatever definition that + is documented, but not **not** exported using EXPORT_SYMBOL. + +``functions <name [, names [, ...]]>`` + Inserts the documentation of function(s), struct(s) or whatever + definition(s) named ``name``. + +``module <prefix-id>`` + The option ``:module: <id-prefix>`` sets a module-name. The module-name is + used as a prefix for automatic generated IDs (reference anchors). + +``snippets <name [, names [, ...]]>`` + Inserts the source-code passage(s) marked with the snippet ``name``. The + snippet is inserted with a `code-block:: <http://www.sphinx-doc.org/en/stable/markup/code.html>`_ + directive. + + The next options make only sense in conjunction with option ``snippets``: + + ``:language: <highlighter>`` + Set highlighting language of the snippet code-block. + + ``:linenos:`` + Set line numbers in the snippet code-block. + +``debug`` + Inserts a code-block with the generated reST source. This might somtimes + helpful to see how the kernel-doc parser transforms the kernel-doc markup to + reST markup. + +ducumentation blocks +==================== + +The following example inserts the documentation block with the title "Theory of +Operation". + +.. code-block:: rst + + .. kernel-doc:: ./all-in-a-tumble.h + :doc: Theory of Operation + :module: example + +With the module name "example" the title refers by: + +.. code-block:: rst + + Rendered example: :ref:`example.theory-of-operation` + +Rendered example: :ref:`example.theory-of-operation` + +functions +========= + +The following example inserts the documentation of struct 'user_function'. + +.. code-block:: rst + + .. kernel-doc:: ./all-in-a-tumble.h + :functions: user_function + :module: example + +.. code-block:: rst + + * Rendered example by ID with module prefix: :ref:`example.user_function` + * Function reference: :c:func:`user_function` + +* Rendered example by ID with module prefix: :ref:`example.user_function` +* Function reference: :c:func:`user_function` + + +structs, unions, enums and typedefs +=================================== + +The following example inserts the documentation of struct 'my_long_struct'. + +.. code-block:: rst + + .. kernel-doc:: ./all-in-a-tumble.h + :functions: my_long_struct + :module: example + +.. code-block:: rst + + * Rendered example by ID with module prefix: :ref:`example.my_long_struct` + * Type reference: :c:type:`my_long_struct` or the alternativ notation + with title :c:type:`struct my_long_struct <my_long_struct>` + +* Rendered example by ID with module prefix: :ref:`example.my_long_struct` +* Type reference: :c:type:`my_long_struct` or the alternativ notation + with title :c:type:`struct my_long_struct <my_long_struct>` + +Snippets +======== + +The kernel-doc Parser supports a comment-markup for +:ref:`kernel-doc-syntax-snippets`. By example; The directive of the shown +code-snippet below is: + +.. code-block:: rst + + .. kernel-doc:: ./all-in-a-tumble.h + :snippets: hello-world + :language: c + :linenos: + +.. kernel-doc:: ./all-in-a-tumble.h + :snippets: hello-world + :language: c + :linenos: + diff --git a/Documentation/books/kernel-doc-HOWTO/kernel-doc-examples.rst b/Documentation/books/kernel-doc-HOWTO/kernel-doc-examples.rst new file mode 100644 index 0000000..4c3ba3b --- /dev/null +++ b/Documentation/books/kernel-doc-HOWTO/kernel-doc-examples.rst @@ -0,0 +1,16 @@ +.. -*- coding: utf-8; mode: rst -*- +.. include:: refs.txt + +.. _kernel-doc-examples: + +===================== +Examples & test cases +===================== + +.. toctree:: + :maxdepth: 2 + + all-in-a-tumble-src + all-in-a-tumble + + diff --git a/Documentation/books/kernel-doc-HOWTO/kernel-doc-intro.rst b/Documentation/books/kernel-doc-HOWTO/kernel-doc-intro.rst new file mode 100644 index 0000000..8cad730 --- /dev/null +++ b/Documentation/books/kernel-doc-HOWTO/kernel-doc-intro.rst @@ -0,0 +1,85 @@ +.. -*- coding: utf-8; mode: rst -*- +.. include:: refs.txt + +.. _kernel-doc-intro: + +================ +kernel-doc intro +================ + +In order to provide good documentation of kernel functions and data structures, +please use the following conventions to format your kernel-doc comments in Linux +kernel source. + +We also look to provide kernel-doc formatted documentation for functions +externally visible to other kernel files (not marked "static"). We also +recommend providing kernel-doc formatted documentation for private (file +"static") routines, for consistency of kernel source code layout. But this is +lower priority and at the discretion of the MAINTAINER of that kernel source +file. Data structures visible in kernel include files should also be documented +using kernel-doc formatted comments. + +The opening comment mark ``/**`` is reserved for kernel-doc comments. Only +comments so marked will be considered by the kernel-doc tools, and any comment +so marked must be in kernel-doc format. The closing comment marker for +kernel-doc comments can be either ``*/`` or ``**/``, but ``*/`` is preferred in +the Linux kernel tree. + +.. hint:: + + 1. Do not use ``/**`` to be begin a comment block unless the comment block + contains kernel-doc formatted comments. + + 2. We definitely need kernel-doc formatted documentation for functions that + are exported to loadable modules using EXPORT_SYMBOL. + + 3. Kernel-doc comments should be placed just before the function or data + structure being described. + + +Example kernel-doc function comment: + +.. code-block:: c + + /** + * foobar() - short function description of foobar + * @arg1: Describe the first argument to foobar. + * @arg2: Describe the second argument to foobar. + * One can provide multiple line descriptions + * for arguments. + * + * A longer description, with more discussion of the function foobar() + * that might be useful to those using or modifying it. Begins with + * empty comment line, and may include additional embedded empty + * comment lines. + * + * The longer description can have multiple paragraphs. + * + * Return: Describe the return value of foobar. + */ + +The short description following the subject can span multiple lines and ends +with an ``@name`` description, an empty line or the end of the comment block. +The kernel-doc function comments describe each parameter to the function, in +order, with the ``@name`` lines. The ``@name`` descriptions must begin on the +very next line following this opening short function description line, with no +intervening empty comment lines. If a function parameter is ``...`` (varargs), +it should be listed in kernel-doc notation as:: + + * @...: description + +The return value, if any, should be described in a dedicated section named +``Return``. Beside functions you can also write documentation for structs, +unions, enums and typedefs. Example kernel-doc data structure comment.:: + + /** + * struct blah - the basic blah structure + * @mem1: describe the first member of struct blah + * @mem2: describe the second member of struct blah, + * perhaps with more lines and words. + * + * Longer description of this structure. + */ + +The kernel-doc data structure comments describe each structure member in the +data structure, with the ``@name`` lines. diff --git a/Documentation/books/kernel-doc-HOWTO/kernel-doc-syntax.rst b/Documentation/books/kernel-doc-HOWTO/kernel-doc-syntax.rst new file mode 100644 index 0000000..3037941 --- /dev/null +++ b/Documentation/books/kernel-doc-HOWTO/kernel-doc-syntax.rst @@ -0,0 +1,171 @@ +.. -*- coding: utf-8; mode: rst -*- +.. include:: refs.txt + +.. _kernel-doc-syntax: + +================== +kernel-doc syntax +================== + +In the following examples, + +* ``(...)?`` signifies optional structure and +* ``(...)*`` signifies 0 or more structure elements + +The definition (or DOC) name is the section header. The section header names +must be unique per source file. + +.. _kernel-doc-syntax-functions: + +functions +========= + +The format of the block comment is like this:: + + /** + * function_name(:)? (- short description)? + (* @parameterx: (description of parameter x)?)* + (* a blank line)? + * (Description:)? (Description of function)? + * (section header: (section description)? )* + (*)?*/ + +All *description* text can span multiple lines, although the +``function_name`` & its short description are traditionally on a single line. +Description text may also contain blank lines (i.e., lines that contain only a +"*"). + +.. ???? +.. Avoid putting a spurious blank line after the function name, or else the +.. description will be repeated! +.. ???? + +So, the trivial example would be: + +.. code-block:: c + + /** + * my_function + */ + +If the Description: header tag is omitted, then there must be a blank line +after the last parameter specification.: + +.. code-block:: c + + /** + * my_function - does my stuff + * @my_arg: its mine damnit + * + * Does my stuff explained. + */ + +or, could also use: + +.. code-block:: c + + /** + * my_function - does my stuff + * @my_arg: its mine damnit + * Description: Does my stuff explained. + */ + +You can also add additional sections. When documenting kernel functions you +should document the ``Context:`` of the function, e.g. whether the functions can +be called form interrupts. Unlike other sections you can end it with an empty +line. + +A non-void function should have a ``Return:`` section describing the return +value(s). Example-sections should contain the string ``EXAMPLE`` so that +they are marked appropriately in the output format. + +.. kernel-doc:: ./all-in-a-tumble.h + :snippets: user_function + :language: c + :linenos: + +Rendered example: :ref:`example.user_function` + +.. _kernel-doc-syntax-misc-types: + +structs, unions, enums and typedefs +=================================== + +Beside functions you can also write documentation for structs, unions, enums and +typedefs. Instead of the function name you must write the name of the +declaration; the ``struct``, ``union``, ``enum`` or ``typedef`` must always +precede the name. Nesting of declarations is not supported. Use the +``@argument`` mechanism to document members or constants. + +Inside a struct description, you can use the 'private:' and 'public:' comment +tags. Structure fields that are inside a 'private:' area are not listed in the +generated output documentation. The 'private:' and 'public:' tags must begin +immediately following a ``/*`` comment marker. They may optionally include +comments between the ``:`` and the ending ``*/`` marker. + +.. kernel-doc:: ./all-in-a-tumble.h + :snippets: my_struct + :language: c + :linenos: + +Rendered example: :ref:`example.my_struct` + +All descriptions can be multiline, except the short function description. +For really longs structs, you can also describe arguments inside the body of +the struct. + +.. kernel-doc:: ./all-in-a-tumble.h + :snippets: my_long_struct + :language: c + :linenos: + +Rendered example: :ref:`example.my_long_struct` + +This should be used only for struct and enum members. + +.. _kernel-doc-syntax-doc: + +ducumentation blocks +==================== + +To facilitate having source code and comments close together, you can include +kernel-doc documentation blocks that are *free-form* comments instead of being +kernel-doc for functions, structures, unions, enums, or typedefs. This could be +used for something like a theory of operation for a driver or library code, for +example. + +This is done by using a ``DOC:`` section keyword with a section title. A small +example: + +.. kernel-doc:: ./all-in-a-tumble.h + :snippets: theory-of-operation + :language: c + :linenos: + +Rendered example: :ref:`example.theory-of-operation` + +.. _kernel-doc-syntax-snippets: + +Snippets +======== + +The kernel-doc Parser supports a comment-markup for snippets out of the source +code. To start a region to snip insert:: + + /* parse-SNIP: <snippet-name> */ + +The snippet region stops with a new snippet region or at the next:: + + /* parse-SNAP: */ + +A small example: + +.. code-block:: c + + /* parse-SNIP: hello-world */ + #include<stdio.h> + int main() { + printf("Hello World\n"); + return 0; + } + /* parse-SNAP: */ diff --git a/Documentation/books/kernel-doc-HOWTO/reST-kernel-doc-mode.rst b/Documentation/books/kernel-doc-HOWTO/reST-kernel-doc-mode.rst new file mode 100644 index 0000000..5cfe59f --- /dev/null +++ b/Documentation/books/kernel-doc-HOWTO/reST-kernel-doc-mode.rst @@ -0,0 +1,120 @@ +.. -*- coding: utf-8; mode: rst -*- +.. include:: refs.txt + +.. _reST-kernel-doc-mode: + +==================== +reST kernel-doc mode +==================== + +To get in use of the fully reST_ add the following comment (e.g.) at the top of +your source code file (or at any line reST content starts).:: + + /* parse-markup: reST */ + +In reST mode the kernel-doc parser pass through all text / markups unchanged to +the reST toolchain including any whitespace. To toggle back to +:ref:`vintage-kernel-doc-mode` type the following line:: + + /* parse-markup: kernel-doc */ + +Within reST mode, most of the *vintage* kernel-doc markup -- as described in +:ref:`kernel-doc-syntax` -- stays unchanged, except the vintage-highlighting +markup and the treatment of whitespaces in description blocks. The *vintage +highlighting* markup is not supported in reST mode, because it conflicts with +the reST markup syntax. + +The reST syntax brings it's own markup to refer and highlight function, +structs or whatever definition e.g.: + +* functions ... + + .. code-block:: rst + + :c:func:`foo_func` + +* structs ... + + .. code-block:: rst + + :c:type:`stuct foo_struct` + +If you are familiar with the vintage style, first this might be a cons-change +for you, but take in account, that you get a expressive ASCII markup on the +pro-side. + + +reST section structure +====================== + +Since a section title in reST mode needs a line break after the colon, the colon +handling is less ugly (:ref:`vintage-mode-quirks`). E.g.:: + + prints out: hello world + +is rendered as expected in one line. If non text follows the colon, a section +is inserted. To avoid sectioning in any case, place a space in front of the column.:: + + lorem list : + + * lorem + * ipsum + +On the opposite, super-short sections like:: + + Return: sum of a and b + +are no longer supported, you have to enter at least one line break:: + + Return: + sum of a and b + +Beside these *sectioning* of the kernel-doc syntax, reST has it's own chapter, +section etc. markup (e.g. see `Sections +<http://www.sphinx-doc.org/en/stable/rest.html#sections>`_). Normally, there are +no heading levels assigned to certain characters as the structure is determined +from the succession of headings. However, there is a common convention, which is +used by the kernel-doc parser also: + +* ``#`` with overline, for parts +* ``*`` with overline, for chapters +* ``=`` for sections +* ``-`` for subsections +* ``^`` for subsubsections +* ``"`` for paragraphs + +Within kernel-doc comments you should use this sectioning with care. A +kernel-doc section like the "Return" section above is translated into a reST +section with the following markup. + +.. code-block:: rst + + Return + ------ + + sum of a and b + +As you see, a kernel-doc section is at reST *subsection* level. This means, you +can only use the following *sub-levels* within a kernel-doc section. + +* ``^`` for subsubsections +* ``"`` for paragraphs + + +further references +================== + +Here are some handy links about reST_ and the `Sphinx markup constructs`_: + +* reST_ primer, `reST (quickref)`_, `reST (spec)`_ +* `Sphinx markup constructs`_ +* `sphinx domains`_ +* `sphinx cross refences`_ +* `intersphinx`_, `sphinx.ext.intersphinx`_ +* `sphinx-doc`_, `sphinx-doc FAQ`_ +* `docutils`_, `docutils FAQ`_ + +In absence of a more detailed C style guide for documentation, the `Python's +Style Guide for documentating +<https://docs.python.org/devguide/documenting.html#style-guide>`_ provides a +good orientation. diff --git a/Documentation/books/kernel-doc-HOWTO/refs.txt b/Documentation/books/kernel-doc-HOWTO/refs.txt new file mode 100644 index 0000000..6d96765 --- /dev/null +++ b/Documentation/books/kernel-doc-HOWTO/refs.txt @@ -0,0 +1,15 @@ +.. _`reST (spec)`: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html +.. _`reST (quickref)`: http://docutils.sourceforge.net/docs/user/rst/quickref.html + +.. _`reST`: http://www.sphinx-doc.org/en/stable/rest.html +.. _`Sphinx markup constructs`: http://www.sphinx-doc.org/en/stable/markup/index.html +.. _`sphinx-doc`: http://www.sphinx-doc.org/ +.. _`sphinx-doc FAQ`: http://www.sphinx-doc.org/en/stable/faq.html +.. _`sphinx domains`: http://www.sphinx-doc.org/en/stable/domains.html +.. _`sphinx cross refences`: http://www.sphinx-doc.org/en/stable/markup/inline.html#cross-referencing-arbitrary-locations +.. _`sphinx.ext.intersphinx`: http://www.sphinx-doc.org/en/stable/ext/intersphinx.html#module-sphinx.ext.intersphinx +.. _`intersphinx`: http://www.sphinx-doc.org/en/stable/ext/intersphinx.html +.. _`sphinx config`: http://www.sphinx-doc.org/en/stable/config.html + +.. _`docutils`: http://docutils.sourceforge.net/docs/index.html +.. _`docutils FAQ`: http://docutils.sourceforge.net/FAQ.html diff --git a/Documentation/books/kernel-doc-HOWTO/table-markup.rst b/Documentation/books/kernel-doc-HOWTO/table-markup.rst new file mode 100644 index 0000000..38a6de0 --- /dev/null +++ b/Documentation/books/kernel-doc-HOWTO/table-markup.rst @@ -0,0 +1,499 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _`Emacs Table Mode`: https://www.emacswiki.org/emacs/TableMode +.. _`Online Tables Generator`: http://www.tablesgenerator.com/text_tables +.. _`OASIS XML Exchange Table Model`: https://www.oasis-open.org/specs/tm9901.html + + +.. _xref_table_concerns: + +============ +About tables +============ + +First: the rest-flat-table_ directive is preferred in the Linux kernel tree. + +Internaly, the docutils uses a representation according to the `OASIS XML +Exchange Table Model`_ (same as DocBook). The *OASIS Table Model* gives a huge +bandwith of possibilities to form tables. This often seduce authors to force a +specific layout. Misuse of tables in this manner is not recommended, because it +breaks the separation of *presentation from content* which most often ends in +problems in range of output formats. Tables (and preformated text like source +code listings) should be used advisedly. In a HTML output, the horizontal and +vertical expansion is handled by a scrollbar. On print medias (paper / pdf) +there is no scrollbar, automaticaly (page-) breaking a table (or line-breaking a +preformated text) in the layout process ends mostly in a unwanted results. + +.. hint:: + + Tables and preformated text in itself violate the separation of *presentation + from content*, but we will never be able to entirely renounce them. Use them + with care, if your content should be rendered well, in wide variation of + output formats. + + +ASCII-art tables +================ + +ASCII-art tables might be comfortable for readers of the text-files, but they +have huge disadvantages in the creation and modifying. First, they are hard to +edit. Think about adding a row or a column to a ASCII-art table or adding a +paraggraph in a cell, it is a nightmare on big tables. Second the diff of +modifing ASCII-art tables is not meaningfull, e.g. widening a cell generates a +diff in which also changes are included, which are only ascribable to the +ASCII-art (see also :ref:`list-table-directives`). + +* `Emacs Table Mode`_ +* `Online Tables Generator`_ + + +Simple tables +------------- + +simple tables allow *colspan* but not *rowspan*: + +.. code-block:: none + + ====== ====== ====== + Inputs Output + ------------- ------ + A B A or B + ====== ====== ====== + False + -------------------- + True + -------------------- + True False True + ------ ------ ------ + False True + ====== ============= + +Rendered as: + +====== ====== ====== + Inputs Output +------------- ------ +A B A or B +====== ====== ====== +False +-------------------- +True +-------------------- +True False True +------ ------ ------ +False True +====== ============= + + +Grid tables +----------- + +grid tables allow colspan *colspan* and *rowspan*: + +.. code-block:: rst + + +------------+------------+-----------+ + | Header 1 | Header 2 | Header 3 | + +============+============+===========+ + | body row 1 | column 2 | column 3 | + +------------+------------+-----------+ + | body row 2 | Cells may span columns.| + +------------+------------+-----------+ + | body row 3 | Cells may | - Cells | + +------------+ span rows. | - contain | + | body row 4 | | - blocks. | + +------------+------------+-----------+ + +Rendered as: + ++------------+------------+-----------+ +| Header 1 | Header 2 | Header 3 | ++============+============+===========+ +| body row 1 | column 2 | column 3 | ++------------+------------+-----------+ +| body row 2 | Cells may span columns.| ++------------+------------+-----------+ +| body row 3 | Cells may | - Cells | ++------------+ span rows. | - contain | +| body row 4 | | - blocks. | ++------------+------------+-----------+ + +.. _list-table-directives: + +List table directives +===================== + +The *list table* formats are double stage list, compared to the ASCII-art they +migth not be as comfortable for readers of the text-files. Their advantage is, +that they are easy to create/modify and that the diff of a modification is much +more meaningfull, because it is limited to the modified content. + +.. _rest-list-table: + +list-table +---------- + +The ``list-tables`` has no ability to *colspan* nor *rowspan*: + +.. code-block:: rst + + .. list-table:: table title + :header-rows: 1 + :stub-columns: 1 + + * - .. + - head col 1 + - head col 2 + + * - stub col row 1 + - column + - column + + * - stub col row 2 + - column + - column + + * - stub col row 3 + - column + - column + + +Rendered as: + +.. list-table:: table title + :header-rows: 1 + :stub-columns: 1 + + * - .. + - head col 1 + - head col 2 + + * - stub col row 1 + - column + - column + + * - stub col row 2 + - column + - column + + * - stub col row 3 + - column + - column + +.. _rest-flat-table: + +flat-table +---------- + +The ``flat-table`` (:py:class:`FlatTable`) is a double-stage list similar +to the ``list-table`` with some additional features: + +* *column-span*: with the role ``cspan`` a cell can be extended through + additional columns + +* *row-span*: with the role ``rspan`` a cell can be extended through + additional rows + +* *auto span* rightmost cell of a table row over the missing cells on the right + side of that table-row. With Option ``:fill-cells:`` this behavior can + changed from *auto span* to *auto fill*, which automaticly inserts (empty) + cells instead of spanning the last cell. + +options: + +:header-rows: [int] count of header rows +:stub-columns: [int] count of stub columns +:widths: [[int] [int] ... ] widths of columns +:fill-cells: instead of autospann missing cells, insert missing cells + +roles: + +:cspan: [int] additionale columns (*morecols*) +:rspan: [int] additionale rows (*morerows*) + +The example below shows how to use this markup. The first level of the staged +list is the *table-row*. In the *table-row* there is only one markup allowed, +the list of the cells in this *table-row*. Exception are *comments* ( ``..`` ) +and *targets* (e.g. a ref to :ref:`row 2 of table's body <row body 2>`). + +.. code-block:: rst + + .. flat-table:: table title + :header-rows: 2 + :stub-columns: 1 + :widths: 1 1 1 1 2 + + * - :rspan:`1` head / stub + - :cspan:`3` head 1.1-4 + + * - head 2.1 + - head 2.2 + - head 2.3 + - head 2.4 + + * .. row body 1 / this is a comment + + - row 1 + - :rspan:`2` cell 1-3.1 + - cell 1.2 + - cell 1.3 + - cell 1.4 + + * .. Comments and targets are allowed on *table-row* stage. + .. _`row body 2`: + + - row 2 + - cell 2.2 + - :rspan:`1` :cspan:`1` + cell 2.3 with a span over + + * col 3-4 & + * row 2-3 + + * - row 3 + - cell 3.2 + + * - row 4 + - cell 4.1 + - cell 4.2 + - cell 4.3 + - cell 4.4 + + * - row 5 + - cell 5.1 with automatic span to rigth end + + * - row 6 + - cell 6.1 + - .. + + +Rendered as: + + .. flat-table:: table title + :header-rows: 2 + :stub-columns: 1 + :widths: 1 1 1 1 2 + + * - :rspan:`1` head / stub + - :cspan:`3` head 1.1-4 + + * - head 2.1 + - head 2.2 + - head 2.3 + - head 2.4 + + * .. row body 1 / this is a comment + + - row 1 + - :rspan:`2` cell 1-3.1 + - cell 1.2 + - cell 1.3 + - cell 1.4 + + * .. Comments and targets are allowed on *table-row* stage. + .. _`row body 2`: + + - row 2 + - cell 2.2 + - :rspan:`1` :cspan:`1` + cell 2.3 with a span over + + * col 3-4 & + * row 2-3 + + * - row 3 + - cell 3.2 + + * - row 4 + - cell 4.1 + - cell 4.2 + - cell 4.3 + - cell 4.4 + + * - row 5 + - cell 5.1 with automatic span to rigth end + + * - row 6 + - cell 6.1 + - .. + + +CSV table +========= + +CSV table might be the choice if you want to include CSV-data from a outstanding +(build) process into your documentation. + +.. code-block:: rst + + .. csv-table:: table title + :header: , Header1, Header2 + :widths: 15, 10, 30 + :stub-columns: 1 + :file: csv_table.txt + +Content of file ``csv_table.txt``: + +.. literalinclude:: csv_table.txt + +Rendered as: + +.. csv-table:: table title + :header: , Header1, Header2 + :widths: 15, 10, 30 + :stub-columns: 1 + :file: csv_table.txt + + +Nested Tables +============= + +Nested tables are ugly, don't use them! This part here is only to show what you +should never do. They are ugly because they cause huge problems in many output +formats and there is always no need for nested tables. + +.. code-block:: rst + + +-----------+----------------------------------------------------+ + | W/NW cell | N/NE cell | + | +-------------+--------------------------+-----------+ + | | W/NW center | N/NE center | E/SE cell | + | | +------------+-------------+ | + | | | +--------+ | E/SE center | | + | | | | nested | | | | + | | | +--------+ | | | + | | | | table | | | | + | | | +--------+ | | | + | +-------------+------------+ | | + | | S/SE center | | | + +-----------+--------------------------+-------------+ | + | S/SW cell | | + +----------------------------------------------------+-----------+ + +Rendered as: Not supported by all sphinx-builders, don't use nested tables!!! + + +raw HTML tables +=============== + +If HTML is the only format you want to render, you could use a raw-import of a +HTML table markup. But be aware, this breaks the separation of *presentation from +content*. HTML-Tables are only rendered within a HTML output. + +.. code-block:: html + + <div class="wy-table-responsive"> + <table class="docutils"> + <thead> + <tr style="font-weight: bold;"> + <td>Owner Module/Drivers</td> + <td>Group</td> + <td>Property Name</td> + <td>Type</td> + <td>Property Values</td> + <td>Object attached</td> + <td>Description/Restrictions</td> + </tr> + </thead> + <tbody> + <tr> + <td rowspan="4">DRM</td> + <td>Generic</td> + <td>"rotation"</td> + <td>BITMASK</td> + <td>{ 0, "rotate-0" }, { 1, "rotate-90" }, { 2, "rotate-180" }, { 3, + "rotate-270" }, { 4, "reflect-x" }, { 5, "reflect-y" }</td> + <td>CRTC, Plane</td> + <td>rotate-(degrees) rotates the image by the specified amount in + degrees in counter clockwise direction. reflect-x and reflect-y + reflects the image along the specified axis prior to rotation</td> + </tr> + + <tr> + <td rowspan="3">Connector</td> + <td>"EDID"</td> + <td>BLOB | IMMUTABLE</td> + <td>0</td> + <td>Connector</td> + <td>Contains id of edid blob ptr object.</td> + </tr> + + <tr> + <td>"DPMS"</td> + <td>ENUM</td> + <td>{ "On", "Standby", "Suspend", "Off" }</td> + <td>Connector</td> + <td>Contains DPMS operation mode value.</td> + </tr> + + <tr> + <td>"PATH"</td> + <td>BLOB | IMMUTABLE</td> + <td>0</td> + <td>Connector</td> + <td>Contains topology path to a connector.</td> + </tr> + </tbody> + </table> + </div> + + + +.. raw:: html + + <div class="wy-table-responsive"> + <table class="docutils"> + <thead> + <tr style="font-weight: bold;"> + <td>Owner Module/Drivers</td> + <td>Group</td> + <td>Property Name</td> + <td>Type</td> + <td>Property Values</td> + <td>Object attached</td> + <td>Description/Restrictions</td> + </tr> + </thead> + <tbody> + <tr> + <td rowspan="4">DRM</td> + <td>Generic</td> + <td>"rotation"</td> + <td>BITMASK</td> + <td>{ 0, "rotate-0" }, { 1, "rotate-90" }, { 2, "rotate-180" }, { 3, + "rotate-270" }, { 4, "reflect-x" }, { 5, "reflect-y" }</td> + <td>CRTC, Plane</td> + <td>rotate-(degrees) rotates the image by the specified amount in + degrees in counter clockwise direction. reflect-x and reflect-y + reflects the image along the specified axis prior to rotation</td> + </tr> + + <tr> + <td rowspan="3">Connector</td> + <td>"EDID"</td> + <td>BLOB | IMMUTABLE</td> + <td>0</td> + <td>Connector</td> + <td>Contains id of edid blob ptr object.</td> + </tr> + + <tr> + <td>"DPMS"</td> + <td>ENUM</td> + <td>{ "On", "Standby", "Suspend", "Off" }</td> + <td>Connector</td> + <td>Contains DPMS operation mode value.</td> + </tr> + + <tr> + <td>"PATH"</td> + <td>BLOB | IMMUTABLE</td> + <td>0</td> + <td>Connector</td> + <td>Contains topology path to a connector.</td> + </tr> + </tbody> + </table> + </div> + +.. include:: refs.txt diff --git a/Documentation/books/kernel-doc-HOWTO/test/parser_test.h b/Documentation/books/kernel-doc-HOWTO/test/parser_test.h new file mode 100644 index 0000000..455b74c --- /dev/null +++ b/Documentation/books/kernel-doc-HOWTO/test/parser_test.h @@ -0,0 +1,332 @@ +/* parse-markup: kernel-doc */ + +/** + * struct v4l2_subdev_core_ops - Define core ops callbacks for subdevs + * + * @log_status: callback for VIDIOC_LOG_STATUS ioctl handler code. + * + * @s_io_pin_config: configure one or more chip I/O pins for chips that + * multiplex different internal signal pads out to IO pins. This function + * takes a pointer to an array of 'n' pin configuration entries, one for + * each pin being configured. This function could be called at times + * other than just subdevice initialization. + * + * @init: initialize the sensor registers to some sort of reasonable default + * values. Do not use for new drivers and should be removed in existing + * drivers. + * + * @load_fw: load firmware. + * + * @reset: generic reset command. The argument selects which subsystems to + * reset. Passing 0 will always reset the whole chip. Do not use for new + * drivers without discussing this first on the linux-media mailinglist. + * There should be no reason normally to reset a device. + * + * @s_gpio: set GPIO pins. Very simple right now, might need to be extended with + * a direction argument if needed. + * + * @queryctrl: callback for VIDIOC_QUERYCTL ioctl handler code. + * + * @g_ctrl: callback for VIDIOC_G_CTRL ioctl handler code. + * + * @s_ctrl: callback for VIDIOC_S_CTRL ioctl handler code. + * + * @g_ext_ctrls: callback for VIDIOC_G_EXT_CTRLS ioctl handler code. + * + * @s_ext_ctrls: callback for VIDIOC_S_EXT_CTRLS ioctl handler code. + * + * @try_ext_ctrls: callback for VIDIOC_TRY_EXT_CTRLS ioctl handler code. + * + * @querymenu: callback for VIDIOC_QUERYMENU ioctl handler code. + * + * @ioctl: called at the end of ioctl() syscall handler at the V4L2 core. + * used to provide support for private ioctls used on the driver. + * + * @compat_ioctl32: called when a 32 bits application uses a 64 bits Kernel, + * in order to fix data passed from/to userspace. + * + * @g_register: callback for VIDIOC_G_REGISTER ioctl handler code. + * + * @s_register: callback for VIDIOC_G_REGISTER ioctl handler code. + * + * @s_power: puts subdevice in power saving mode (on == 0) or normal operation + * mode (on == 1). + * + * @interrupt_service_routine: Called by the bridge chip's interrupt service + * handler, when an interrupt status has be raised due to this subdev, + * so that this subdev can handle the details. It may schedule work to be + * performed later. It must not sleep. *Called from an IRQ context*. + * + * @subscribe_event: used by the drivers to request the control framework that + * for it to be warned when the value of a control changes. + * + * @unsubscribe_event: remove event subscription from the control framework. + * + * @registered_async: the subdevice has been registered async. + * + * This is a copy&paste of a more complexe struct, just for testing. + */ +struct v4l2_subdev_core_ops { + int (*log_status)(struct v4l2_subdev *sd); + int (*s_io_pin_config)(struct v4l2_subdev *sd, size_t n, + struct v4l2_subdev_io_pin_config *pincfg); + int (*init)(struct v4l2_subdev *sd, u32 val); + int (*load_fw)(struct v4l2_subdev *sd); + int (*reset)(struct v4l2_subdev *sd, u32 val); + int (*s_gpio)(struct v4l2_subdev *sd, u32 val); + int (*queryctrl)(struct v4l2_subdev *sd, struct v4l2_queryctrl *qc); + int (*g_ctrl)(struct v4l2_subdev *sd, struct v4l2_control *ctrl); + int (*s_ctrl)(struct v4l2_subdev *sd, struct v4l2_control *ctrl); + int (*g_ext_ctrls)(struct v4l2_subdev *sd, struct v4l2_ext_controls *ctrls); + int (*s_ext_ctrls)(struct v4l2_subdev *sd, struct v4l2_ext_controls *ctrls); + int (*try_ext_ctrls)(struct v4l2_subdev *sd, struct v4l2_ext_controls *ctrls); + int (*querymenu)(struct v4l2_subdev *sd, struct v4l2_querymenu *qm); + long (*ioctl)(struct v4l2_subdev *sd, unsigned int cmd, void *arg); +#ifdef CONFIG_COMPAT + long (*compat_ioctl32)(struct v4l2_subdev *sd, unsigned int cmd, + unsigned long arg); +#endif +#ifdef CONFIG_VIDEO_ADV_DEBUG + int (*g_register)(struct v4l2_subdev *sd, struct v4l2_dbg_register *reg); + int (*s_register)(struct v4l2_subdev *sd, const struct v4l2_dbg_register *reg); +#endif + int (*s_power)(struct v4l2_subdev *sd, int on); + int (*interrupt_service_routine)(struct v4l2_subdev *sd, + u32 status, bool *handled); + int (*subscribe_event)(struct v4l2_subdev *sd, struct v4l2_fh *fh, + struct v4l2_event_subscription *sub); + int (*unsubscribe_event)(struct v4l2_subdev *sd, struct v4l2_fh *fh, + struct v4l2_event_subscription *sub); + int (*registered_async)(struct v4l2_subdev *sd); +}; + +/** + * DOC: Media Controller + * + * The media controller userspace API is documented in DocBook format in + * Documentation/DocBook/media/v4l/media-controller.xml. This document focus + * on the kernel-side implementation of the media framework. + * + * * Abstract media device model: + * + * Discovering a device internal topology, and configuring it at runtime, is one + * of the goals of the media framework. To achieve this, hardware devices are + * modelled as an oriented graph of building blocks called entities connected + * through pads. + * + * An entity is a basic media hardware building block. It can correspond to + * a large variety of logical blocks such as physical hardware devices + * (CMOS sensor for instance), logical hardware devices (a building block + * in a System-on-Chip image processing pipeline), DMA channels or physical + * connectors. + * + * A pad is a connection endpoint through which an entity can interact with + * other entities. Data (not restricted to video) produced by an entity + * flows from the entity's output to one or more entity inputs. Pads should + * not be confused with physical pins at chip boundaries. + * + * A link is a point-to-point oriented connection between two pads, either + * on the same entity or on different entities. Data flows from a source + * pad to a sink pad. + * + * + * * Media device: + * + * A media device is represented by a struct &media_device instance, defined in + * include/media/media-device.h. Allocation of the structure is handled by the + * media device driver, usually by embedding the &media_device instance in a + * larger driver-specific structure. + * + * Drivers register media device instances by calling + * __media_device_register() via the macro media_device_register() + * and unregistered by calling + * media_device_unregister(). + * + * * Entities, pads and links: + * + * - Entities + * + * Entities are represented by a struct &media_entity instance, defined in + * include/media/media-entity.h. The structure is usually embedded into a + * higher-level structure, such as a v4l2_subdev or video_device instance, + * although drivers can allocate entities directly. + * + * Drivers initialize entity pads by calling + * media_entity_pads_init(). + * + * Drivers register entities with a media device by calling + * media_device_register_entity() + * and unregistred by calling + * media_device_unregister_entity(). + * + * - Interfaces + * + * Interfaces are represented by a struct &media_interface instance, defined in + * include/media/media-entity.h. Currently, only one type of interface is + * defined: a device node. Such interfaces are represented by a struct + * &media_intf_devnode. + * + * Drivers initialize and create device node interfaces by calling + * media_devnode_create() + * and remove them by calling: + * media_devnode_remove(). + * + * - Pads + * + * Pads are represented by a struct &media_pad instance, defined in + * include/media/media-entity.h. Each entity stores its pads in a pads array + * managed by the entity driver. Drivers usually embed the array in a + * driver-specific structure. + * + * Pads are identified by their entity and their 0-based index in the pads + * array. + * Both information are stored in the &media_pad structure, making the + * &media_pad pointer the canonical way to store and pass link references. + * + * Pads have flags that describe the pad capabilities and state. + * + * %MEDIA_PAD_FL_SINK indicates that the pad supports sinking data. + * %MEDIA_PAD_FL_SOURCE indicates that the pad supports sourcing data. + * + * NOTE: One and only one of %MEDIA_PAD_FL_SINK and %MEDIA_PAD_FL_SOURCE must + * be set for each pad. + * + * - Links + * + * Links are represented by a struct &media_link instance, defined in + * include/media/media-entity.h. There are two types of links: + * + * 1. pad to pad links: + * + * Associate two entities via their PADs. Each entity has a list that points + * to all links originating at or targeting any of its pads. + * A given link is thus stored twice, once in the source entity and once in + * the target entity. + * + * Drivers create pad to pad links by calling: + * media_create_pad_link() and remove with media_entity_remove_links(). + * + * 2. interface to entity links: + * + * Associate one interface to a Link. + * + * Drivers create interface to entity links by calling: + * media_create_intf_link() and remove with media_remove_intf_links(). + * + * NOTE: + * + * Links can only be created after having both ends already created. + * + * Links have flags that describe the link capabilities and state. The + * valid values are described at media_create_pad_link() and + * media_create_intf_link(). + * + * Graph traversal: + * + * The media framework provides APIs to iterate over entities in a graph. + * + * To iterate over all entities belonging to a media device, drivers can use + * the media_device_for_each_entity macro, defined in + * include/media/media-device.h. + * + * struct media_entity *entity; + * + * media_device_for_each_entity(entity, mdev) { + * // entity will point to each entity in turn + * ... + * } + * + * Drivers might also need to iterate over all entities in a graph that can be + * reached only through enabled links starting at a given entity. The media + * framework provides a depth-first graph traversal API for that purpose. + * + * Note that graphs with cycles (whether directed or undirected) are *NOT* + * supported by the graph traversal API. To prevent infinite loops, the graph + * traversal code limits the maximum depth to MEDIA_ENTITY_ENUM_MAX_DEPTH, + * currently defined as 16. + * + * Drivers initiate a graph traversal by calling + * media_entity_graph_walk_start() + * + * The graph structure, provided by the caller, is initialized to start graph + * traversal at the given entity. + * + * Drivers can then retrieve the next entity by calling + * media_entity_graph_walk_next() + * + * When the graph traversal is complete the function will return NULL. + * + * Graph traversal can be interrupted at any moment. No cleanup function call + * is required and the graph structure can be freed normally. + * + * Helper functions can be used to find a link between two given pads, or a pad + * connected to another pad through an enabled link + * media_entity_find_link() and media_entity_remote_pad() + * + * Use count and power handling: + * + * Due to the wide differences between drivers regarding power management + * needs, the media controller does not implement power management. However, + * the &media_entity structure includes a use_count field that media drivers + * can use to track the number of users of every entity for power management + * needs. + * + * The &media_entity.@use_count field is owned by media drivers and must not be + * touched by entity drivers. Access to the field must be protected by the + * &media_device.@graph_mutex lock. + * + * Links setup: + * + * Link properties can be modified at runtime by calling + * media_entity_setup_link() + * + * Pipelines and media streams: + * + * When starting streaming, drivers must notify all entities in the pipeline to + * prevent link states from being modified during streaming by calling + * media_entity_pipeline_start(). + * + * The function will mark all entities connected to the given entity through + * enabled links, either directly or indirectly, as streaming. + * + * The &media_pipeline instance pointed to by the pipe argument will be stored + * in every entity in the pipeline. Drivers should embed the &media_pipeline + * structure in higher-level pipeline structures and can then access the + * pipeline through the &media_entity pipe field. + * + * Calls to media_entity_pipeline_start() can be nested. The pipeline pointer + * must be identical for all nested calls to the function. + * + * media_entity_pipeline_start() may return an error. In that case, it will + * clean up any of the changes it did by itself. + * + * When stopping the stream, drivers must notify the entities with + * media_entity_pipeline_stop(). + * + * If multiple calls to media_entity_pipeline_start() have been made the same + * number of media_entity_pipeline_stop() calls are required to stop streaming. + * The &media_entity pipe field is reset to NULL on the last nested stop call. + * + * Link configuration will fail with -%EBUSY by default if either end of the + * link is a streaming entity. Links that can be modified while streaming must + * be marked with the %MEDIA_LNK_FL_DYNAMIC flag. + * + * If other operations need to be disallowed on streaming entities (such as + * changing entities configuration parameters) drivers can explicitly check the + * media_entity stream_count field to find out if an entity is streaming. This + * operation must be done with the media_device graph_mutex held. + * + * Link validation: + * + * Link validation is performed by media_entity_pipeline_start() for any + * entity which has sink pads in the pipeline. The + * &media_entity.@link_validate() callback is used for that purpose. In + * @link_validate() callback, entity driver should check that the properties of + * the source pad of the connected entity and its own sink pad match. It is up + * to the type of the entity (and in the end, the properties of the hardware) + * what matching actually means. + * + * Subsystems should facilitate link validation by providing subsystem specific + * helper functions to provide easy access for commonly needed information, and + * in the end provide a way to use driver-specific callbacks. + */ diff --git a/Documentation/books/kernel-doc-HOWTO/vintage-kernel-doc-mode.rst b/Documentation/books/kernel-doc-HOWTO/vintage-kernel-doc-mode.rst new file mode 100644 index 0000000..a49bc25 --- /dev/null +++ b/Documentation/books/kernel-doc-HOWTO/vintage-kernel-doc-mode.rst @@ -0,0 +1,100 @@ +.. -*- coding: utf-8; mode: rst -*- +.. include:: refs.txt + +.. _vintage-kernel-doc-mode: + +======================= +Vintage kernel-doc mode +======================= + +All kernel-doc markup is processed as described in :ref:`kernel-doc-syntax`, all +descriptive text is further processed, scanning for the following special +patterns, which are highlighted appropriately. + +* ``funcname()`` - function +* ``$ENVVAR`` - environmental variable +* ``&struct name`` - name of a structure (up to two words including ``struct``) +* ``@parameter`` - name of a parameter +* ``%CONST`` - name of a constant. + +These highlighted patterns are not used when you are using the reST addition +(:ref:`reST-kernel-doc-mode`). This is, because reST brings it's own markup to +refer and highlight function, structs or whatever definition. + +Within the *vintage* kernel-doc mode the kernel-doc parser highlights the pattern +above, but he also dogged ignores any whitespace formatting/markup. + +.. hint:: + + Formatting with whitespaces is substantial for ASCII markups. By this, it's + recommended to use the :ref:`reST-kernel-doc-mode` on any new or changed + comment. + + +.. _vintage-mode-quirks: + +vintage mode quirks +=================== + +In the following, you will find some quirks of the *vintage* kernel-doc mode. + +* Since a colon introduce a new section, you can't use colons. E.g. a comment + line like:: + + prints out: hello world + + will result in a section with the title "prints out" and a paragraph with only + "hello world" in, this is mostly not what you expect. To avoid sectioning, + place a space in front of the column:: + + prints out : hello world + +* The multi-line descriptive text you provide does *not* recognize + line breaks, so if you try to format some text nicely, as in:: + + Return: + 0 - cool + 1 - invalid arg + 2 - out of memory + + this will all run together and produce:: + + Return: 0 - cool 1 - invalid arg 2 - out of memory + +* If the descriptive text you provide has lines that begin with some phrase + followed by a colon, each of those phrases will be taken as a new section + heading, which means you should similarly try to avoid text like:: + + Return: + 0: cool + 1: invalid arg + 2: out of memory + + every line of which would start a new section. Again, probably not what you + were after. + +Determined by the historical development of the kernel-doc comments, the +*vintage* kernel-doc comments contain characters like "*" or strings with +e.g. leading/trailing underscore ("_"), which are inline markups in reST. Here a +short example from a *vintage* comment:: + + <SNIP> ----- + * In contrast to the other drm_get_*_name functions this one here returns a + * const pointer and hence is threadsafe. + <SNAP> ----- + +Within reST markup (the new bas format), the wildcard in the string +``drm_get_*_name`` has to be masked: ``drm_get_\\*_name``. Some more examples +from reST markup: + +* Emphasis "*": like ``*emphasis*`` or ``**emphasis strong**`` +* Leading "_" : is a *anchor* in reST markup (``_foo``). +* Trailing "_: is a reference in reST markup (``foo_``). +* interpreted text: "`" +* inline literals: "``" +* substitution references: "|" + +As long as you in the *vintage* kernel-doc mode, these special strings will be +masked in the reST output and can't be used as *plain-text markup*. + + -- v4.7-rc-2 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
