Date:   Sat, 26 Mar 2022 19:33:37 +0700
From:   Bagas Sanjaya <bagasdotme@...il.com>
To:     linux-doc@...r.kernel.org
Cc:     Bagas Sanjaya <bagasdotme@...il.com>,
        Jonathan Corbet <corbet@....net>,
        "David S. Miller" <davem@...emloft.net>,
        Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
        "Rafael J. Wysocki" <rafael.j.wysocki@...el.com>,
        Jens Axboe <axboe@...nel.dk>,
        Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
        Akira Yokosawa <akiyks@...il.com>, linux-kernel@...r.kernel.org
Subject: [PATCH v2 1/2] Documentation: kernel-doc: Promote "Writing kernel-doc comments" to page title

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@....net>
Cc: "David S. Miller" <davem@...emloft.net>
Cc: Greg Kroah-Hartman <gregkh@...uxfoundation.org>
Cc: "Rafael J. Wysocki" <rafael.j.wysocki@...el.com>
Cc: Jens Axboe <axboe@...nel.dk>
Cc: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
Cc: Akira Yokosawa <akiyks@...il.com>
Cc: linux-kernel@...r.kernel.org
Signed-off-by: Bagas Sanjaya <bagasdotme@...il.com>
---
 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

Powered by blists - more mailing lists