Promote the first heading from chapter heading to page title. While at
it, fix heading inconsistencies by promoting the appropriate headings.
Cc: Jonathan Corbet <corbet@xxxxxxx>
Cc: "David S. Miller" <davem@xxxxxxxxxxxxx>
Cc: Greg Kroah-Hartman <gregkh@xxxxxxxxxxxxxxxxxxx>
Cc: "Rafael J. Wysocki" <rafael.j.wysocki@xxxxxxxxx>
Cc: Jens Axboe <axboe@xxxxxxxxx>
Cc: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
Cc: Akira Yokosawa <akiyks@xxxxxxxxx>
Cc: linux-kernel@xxxxxxxxxxxxxxx
Signed-off-by: Bagas Sanjaya <bagasdotme@xxxxxxxxx>
---
Documentation/doc-guide/kernel-doc.rst | 29 +++++++++++++-------------
1 file changed, 15 insertions(+), 14 deletions(-)
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index 79aaa55d6bcf2b..ea41e05d0e8903 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -1,3 +1,4 @@
+===========================
Writing kernel-doc comments
===========================
@@ -31,7 +32,7 @@ kernel source code layout. This is lower priority and at the discretion
of the maintainer of that kernel source file.
How to format kernel-doc comments
----------------------------------
+=================================
The opening comment mark ``/**`` is used for kernel-doc comments. The
``kernel-doc`` tool will extract comments marked this way. The rest of
@@ -56,7 +57,7 @@ requested to perform extra gcc checks::
make W=n
Function documentation
-----------------------
+======================
The general format of a function and function-like macro kernel-doc comment is::
@@ -88,7 +89,7 @@ ends with an argument description, a blank comment line, or the end of the
comment block.
Function parameters
-~~~~~~~~~~~~~~~~~~~
+-------------------
Each function argument should be described in order, immediately following
the short function description. Do not leave a blank line between the
@@ -116,7 +117,7 @@ be written in kernel-doc notation as::
* @...: description
Function context
-~~~~~~~~~~~~~~~~
+----------------
The context in which a function can be called should be described in a
section named ``Context``. This should include whether the function
@@ -134,7 +135,7 @@ Examples::
* Context: Interrupt context.
Return values
-~~~~~~~~~~~~~
+-------------
The return value, if any, should be described in a dedicated section
named ``Return``.
@@ -166,7 +167,7 @@ named ``Return``.
effect.
Structure, union, and enumeration documentation
------------------------------------------------
+===============================================
The general format of a struct, union, and enum kernel-doc comment is::
@@ -189,7 +190,7 @@ lines, and ends with a member description, a blank comment line, or the
end of the comment block.
Members
-~~~~~~~
+-------
Members of structs, unions and enums should be documented the same way
as function parameters; they immediately succeed the short description
@@ -223,7 +224,7 @@ Example::
};
Nested structs/unions
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
It is possible to document nested structs and unions, like::
@@ -274,7 +275,7 @@ It is possible to document nested structs and unions, like::
should be documented as ``@bar:``
In-line member documentation comments
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------
The structure members may also be documented in-line within the definition.
There are two styles, single-line comments where both the opening ``/**`` and
@@ -311,7 +312,7 @@ on a line of their own, like all other kernel-doc comments::
};
Typedef documentation
----------------------
+=====================
The general format of a typedef kernel-doc comment is::
@@ -336,7 +337,7 @@ Typedefs with function prototypes can also be documented::
typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);
Highlights and cross-references
--------------------------------
+===============================
The following special patterns are recognized in the kernel-doc comment
descriptive text and converted to proper reStructuredText markup and `Sphinx C
@@ -385,7 +386,7 @@ Domain`_ references.
instead. This is mostly for legacy comments.
Cross-referencing from reStructuredText
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=======================================
No additional syntax is needed to cross-reference the functions and types
defined in the kernel-doc comments from reStructuredText documents.
@@ -408,7 +409,7 @@ through the following syntax::
For further details, please refer to the `Sphinx C Domain`_ documentation.
Overview documentation comments
--------------------------------
+===============================
To facilitate having source code and comments close together, you can include
kernel-doc documentation blocks that are free-form comments instead of being
@@ -524,7 +525,7 @@ source.
.. _kernel_doc:
How to use kernel-doc to generate man pages
--------------------------------------------
+===========================================
If you just want to use kernel-doc to generate man pages you can do this
from the kernel git tree::
--
An old man doll... just what I always wanted! - Clara
