summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMarkus Heiser <markus.heiser@darmarIT.de>2016-08-15 16:08:25 +0200
committerJonathan Corbet <corbet@lwn.net>2016-08-22 15:19:22 -0600
commit2c645cd7c4a0d4b35da1e43ec3a5b55a64038157 (patch)
treec18c69bd8fca8a662434864c714b0c884642a85b
parente8f5c617f26626ef4915ffa176f4ae02c9e08531 (diff)
downloadlinux-2c645cd7c4a0d4b35da1e43ec3a5b55a64038157.tar.bz2
doc-rst:c-domain: ref-name of a function declaration
Add option 'name' to the "c:function:" directive. With option 'name' the ref-name of a function can be modified. E.g.:: .. 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:: :c:func:`VIDIOC_LOG_STATUS` Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
-rw-r--r--Documentation/kernel-documentation.rst29
-rw-r--r--Documentation/sphinx/cdomain.py31
2 files changed, 60 insertions, 0 deletions
diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst
index c4eb5049da39..bc4c3f526816 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
-----------
diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py
index d6e66e289808..b1912c80ff77 100644
--- a/Documentation/sphinx/cdomain.py
+++ b/Documentation/sphinx/cdomain.py
@@ -7,8 +7,24 @@ u"""
:copyright: Copyright (C) 2016 Markus Heiser
:license: GPL Version 2, June 1991 see Linux/COPYING for details.
+
+ List of customizations:
+
+ * Add option 'name' to the "c:function:" directive. With option 'name' the
+ ref-name of a function can be modified. E.g.::
+
+ .. 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 function is referenced by::
+
+ * :c:func:`VIDIOC_LOG_STATUS` or
+ * :any:`VIDIOC_LOG_STATUS` (``:any:`` needs sphinx 1.3)
"""
+from docutils.parsers.rst import directives
+
from sphinx.domains.c import CObject as Base_CObject
from sphinx.domains.c import CDomain as Base_CDomain
@@ -29,6 +45,21 @@ class CObject(Base_CObject):
"""
Description of a C language object.
"""
+ option_spec = {
+ "name" : directives.unchanged
+ }
+
+ def handle_signature(self, sig, signode):
+ """Transform a C signature into RST nodes."""
+ fullname = super(CObject, self).handle_signature(sig, signode)
+ if "name" in self.options:
+ if self.objtype == 'function':
+ fullname = self.options["name"]
+ else:
+ # FIXME: handle :name: value of other declaration types?
+ pass
+ return fullname
+
class CDomain(Base_CDomain):