From: Randy Dunlap <rdunlap@infradead.org>
To: Markus Heiser <markus.heiser@darmarIT.de>, corbet@lwn.net
Cc: jani.nikula@intel.com, daniel.vetter@ffwll.ch,
grant.likely@secretlab.ca, mchehab@osg.samsung.com,
keithp@keithp.com, linux-kernel@vger.kernel.org,
linux-doc@vger.kernel.org, hverkuil@xs4all.nl
Subject: Re: [PATCH 3/7] kernel-doc-HOWTO: add kernel-doc specification
Date: Thu, 9 Jun 2016 11:05:12 -0700 [thread overview]
Message-ID: <5759AFD8.5090509@infradead.org> (raw)
In-Reply-To: <1465230745-31358-4-git-send-email-markus.heiser@darmarIT.de>
Hi,
Some spellos and a few questions...
On 06/06/16 09:32, Markus Heiser wrote:
> From: "Heiser, Markus" <markus.heiser@darmarIT.de>
>
> 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@darmarIT.de>
> ---
> 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
next prev parent reply other threads:[~2016-06-09 18:05 UTC|newest]
Thread overview: 23+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-06-06 16:32 [PATCH 0/7] add reST/sphinx-doc to linux documentation Markus Heiser
2016-06-06 16:32 ` [PATCH 1/7] python: add scripts/site-packages Markus Heiser
2016-06-06 16:32 ` [PATCH 2/7] sphinx-doc: add basic sphinx-build infrastructure Markus Heiser
2016-06-06 16:32 ` [PATCH 3/7] kernel-doc-HOWTO: add kernel-doc specification Markus Heiser
2016-06-09 18:05 ` Randy Dunlap [this message]
2016-06-09 18:42 ` Jani Nikula
2016-06-10 16:00 ` Markus Heiser
2016-06-10 16:04 ` Randy Dunlap
2016-06-06 16:32 ` [PATCH 4/7] linuxdoc: add python package linuxdoc Markus Heiser
2016-06-06 16:32 ` [PATCH 5/7] kernel-doc parser: inital python implementation Markus Heiser
2016-06-06 16:32 ` [PATCH 6/7] kernel-doc directive: initial implementation Markus Heiser
2016-06-06 16:32 ` [PATCH 7/7] flat-table " Markus Heiser
2016-06-07 7:54 ` [PATCH 0/7] add reST/sphinx-doc to linux documentation Daniel Vetter
2016-06-07 8:59 ` Jani Nikula
2016-06-07 9:36 ` Markus Heiser
2016-06-07 11:09 ` Jani Nikula
2016-06-07 15:13 ` Markus Heiser
2016-06-07 9:14 ` Markus Heiser
2016-06-08 19:49 ` Jonathan Corbet
2016-06-10 15:25 ` Markus Heiser
2016-06-10 17:19 ` Jani Nikula
2016-06-15 13:01 ` Markus Heiser
2016-06-07 13:47 ` Markus Heiser
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=5759AFD8.5090509@infradead.org \
--to=rdunlap@infradead.org \
--cc=corbet@lwn.net \
--cc=daniel.vetter@ffwll.ch \
--cc=grant.likely@secretlab.ca \
--cc=hverkuil@xs4all.nl \
--cc=jani.nikula@intel.com \
--cc=keithp@keithp.com \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=markus.heiser@darmarIT.de \
--cc=mchehab@osg.samsung.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.