Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 2c645cd7 authored by Markus Heiser's avatar Markus Heiser Committed by Jonathan Corbet
Browse files

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: default avatarMarkus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent e8f5c617

Documentation/kernel-documentation.rst

+29 −0
Original line number Diff line number Diff line
@@ -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

-----------

Documentation/sphinx/cdomain.py

+31 −0
Original line number Diff line number Diff line
@@ -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):