summaryrefslogtreecommitdiffstats
path: root/Documentation/doc-guide/kernel-doc.rst
diff options
context:
space:
mode:
authorNĂ­colas F. R. A. Prado <nfraprado@protonmail.com>2020-09-03 02:58:26 +0200
committerJonathan Corbet <corbet@lwn.net>2020-09-03 21:50:40 +0200
commit7c8b9e3000f82de68373db23819f9585e54186bb (patch)
treec62f09a5aafe8fde68b64da5a195ee126729a14c /Documentation/doc-guide/kernel-doc.rst
parentdocs: Add automatic cross-reference for C types (diff)
downloadlinux-7c8b9e3000f82de68373db23819f9585e54186bb.tar.xz
linux-7c8b9e3000f82de68373db23819f9585e54186bb.zip
kernel-doc: Update "cross-referencing from rST" section to use automarkup
Update text and examples in the "Cross-referencing from reStructuredText" section to reflect that no additional syntax is needed anymore. Signed-off-by: NĂ­colas F. R. A. Prado <nfraprado@protonmail.com> Link: https://lore.kernel.org/r/20200903005747.3900333-3-nfraprado@protonmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'Documentation/doc-guide/kernel-doc.rst')
-rw-r--r--Documentation/doc-guide/kernel-doc.rst33
1 files changed, 17 insertions, 16 deletions
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index fff6604631ea..4fd86c21397b 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -387,22 +387,23 @@ Domain`_ references.
Cross-referencing from reStructuredText
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-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::
-
- See function :c:func:`foo` and struct/union/enum/typedef :c:type:`bar`.
-
-While the type reference works with just the type name, without the
-struct/union/enum/typedef part in front, you may want to use::
-
- See :c:type:`struct foo <foo>`.
- See :c:type:`union bar <bar>`.
- See :c:type:`enum baz <baz>`.
- See :c:type:`typedef meh <meh>`.
-
-This will produce prettier links, and is in line with how kernel-doc does the
-cross-references.
+No additional syntax is needed to cross-reference the functions and types
+defined in the kernel-doc comments from reStructuredText documents.
+Just end function names with ``()`` and write ``struct``, ``union``, ``enum``
+or ``typedef`` before types.
+For example::
+
+ See foo().
+ See struct foo.
+ See union bar.
+ See enum baz.
+ See typedef meh.
+
+However, if you want custom text in the cross-reference link, that can be done
+through the following syntax::
+
+ See :c:func:`my custom link text for function foo <foo>`.
+ See :c:type:`my custom link text for struct bar <bar>`.
For further details, please refer to the `Sphinx C Domain`_ documentation.