From 2c645cd7c4a0d4b35da1e43ec3a5b55a64038157 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Mon, 15 Aug 2016 16:08:25 +0200 Subject: 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 Signed-off-by: Jonathan Corbet --- Documentation/kernel-documentation.rst | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) (limited to 'Documentation/kernel-documentation.rst') 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 ----------- -- cgit v1.2.3 From 0cef67aa651808bac9d79503ebf45246612262fe Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Sep 2016 08:08:00 -0300 Subject: Documentation/SubmitChecklist: update kernel-doc task Task 11 (kernel-doc) still mentions usage of make manpages, but this won't work if the API is documented via Sphinx. So, update it to use either htmldocs or pdfdocs, with are the documentation targets that work for all. While here, add ReST reference to the kernel documentation book. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/kernel-documentation.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'Documentation/kernel-documentation.rst') diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst index bc4c3f526816..ceb80b898bb3 100644 --- a/Documentation/kernel-documentation.rst +++ b/Documentation/kernel-documentation.rst @@ -294,6 +294,8 @@ The kernel-doc extension is included in the kernel source tree, at ``scripts/kernel-doc`` script to extract the documentation comments from the source. +.. _kernel_doc: + Writing kernel-doc comments =========================== -- cgit v1.2.3