Re: [PATCH 3/7] kernel-doc-HOWTO: add kernel-doc specification
From: Randy Dunlap
Date: Thu Jun 09 2016 - 14:06:30 EST
Hi,
Some spellos and a few questions...
On 06/06/16 09:32, Markus Heiser wrote:
> 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:
preset
> +#
> +# * 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
referred
> + * and additional tests.
> + *
> + * The content itself is nonsens / don’t look to close ;-)
nonsense
> + */
> +/* 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.
generated
> + *
> + * 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:
following
> + *
> + * 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
following
> + * 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.
in 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.
complex
> + */
> +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.
what is "dogged"??
> +
> +.. 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
what is "bas"??
> +``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*.
> +
> +
>
My only "requirement" (if I may have one) is that we not introduce big
hurdles to kernel developers adding documentation.
I'm not saying that this is a big hurdle.. I haven't looked at it enough
yet.
--
~Randy