Re: [PATCH 3/7] kernel-doc-HOWTO: add kernel-doc specification

[Randy Dunlap <rdunlap@xxxxxxxxxxxxx>]

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
--
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