Merge remote-tracking branch 'docs-next/docs-next' into devel/docs-next

* docs-next/docs-next: (51 commits)
  docs-rst: add package adjustbox
  docs-rst: Fix an warning when in interactive mode
  docs-rst: Use better colors for note/warning/attention boxes
  docs-rst: conf.py: adjust the size of .. note:: tag
  docs-rst: add support for LaTeX output
  doc-rst: migrate ioctl CEC_DQEVENT to c-domain
  doc-rst: Revert "kernel-doc: fix handling of address_space tags"
  doc-rst: moved *duplicate* warnings to nitpicky mode
  doc-rst:c-domain: ref-name of a function declaration
  doc-rst: add boilerplate to customize c-domain
  docs: Sphinxify gdb-kernel-debugging.txt and move to dev-tools
  docs: sphinxify kmemcheck.txt and move to dev-tools
  docs: sphinxify kmemleak.txt and move it to dev-tools
  docs: sphinxify ubsan.txt and move it to dev-tools
  docs: sphinxify kasan.txt and move to dev-tools
  docs: sphinixfy gcov.txt and move to dev-tools
  docs: sphinxify kcov.txt and move to dev-tools
  docs: sphinxify sparse.txt and move to dev-tools
  docs: sphinxify coccinelle.txt and add it to dev-tools
  docs: create a new dev-tools directory
  ...

1 files changed, 29 insertions, 6 deletions

diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst
index c4eb5049da39..a0dcae15639b 100644
--- a/Documentation/kernel-documentation.rst
+++ b/Documentation/kernel-documentation.rst
@@ -107,6 +107,35 @@ Here are some specific guidelines for the kernel documentation:
   the order as encountered."), having the higher levels the same overall makes
   it easier to follow the documents.
 
+
+the C domain
+------------
+
+The `Sphinx C Domain`_ (name c) is suited for documentation of C API. E.g. a
+function prototype:
+
+.. code-block:: rst
+
+    .. c:function:: int ioctl( int fd, int request )
+
+The C domain of the kernel-doc has some additional features. E.g. you can
+*rename* the reference name of a function with a common name like ``open`` or
+``ioctl``:
+
+.. code-block:: rst
+
+     .. c:function:: int ioctl( int fd, int request )
+        :name: VIDIOC_LOG_STATUS
+
+The func-name (e.g. ioctl) remains in the output but the ref-name changed from
+``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for this function is also
+changed to ``VIDIOC_LOG_STATUS`` and the function can now referenced by:
+
+.. code-block:: rst
+
+     :c:func:`VIDIOC_LOG_STATUS`
+
+
 list tables
 -----------
 
@@ -366,8 +395,6 @@ Domain`_ references.
 Cross-referencing from reStructuredText
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. highlight:: none
-
 To cross-reference the functions and types defined in the kernel-doc comments
 from reStructuredText documents, please use the `Sphinx C Domain`_
 references. For example::
@@ -390,8 +417,6 @@ For further details, please refer to the `Sphinx C Domain`_ documentation.
 Function documentation
 ----------------------
 
-.. highlight:: c
-
 The general format of a function and function-like macro kernel-doc comment is::
 
   /**
@@ -572,8 +597,6 @@ DocBook XML [DEPRECATED]
 Converting DocBook to Sphinx
 ----------------------------
 
-.. highlight:: none
-
 Over time, we expect all of the documents under ``Documentation/DocBook`` to be
 converted to Sphinx and reStructuredText. For most DocBook XML documents, a good
 enough solution is to use the simple ``Documentation/sphinx/tmplcvt`` script,