Em Sat, 26 Mar 2022 19:33:37 +0700
Bagas Sanjaya <[email protected]> escreveu:
> Promote the first heading from chapter heading to page title. While at
> it, fix heading inconsistencies by promoting the appropriate headings.
>
> Cc: Jonathan Corbet <[email protected]>
> Cc: "David S. Miller" <[email protected]>
> Cc: Greg Kroah-Hartman <[email protected]>
> Cc: "Rafael J. Wysocki" <[email protected]>
> Cc: Jens Axboe <[email protected]>
> Cc: Mauro Carvalho Chehab <[email protected]>
> Cc: Akira Yokosawa <[email protected]>
> Cc: [email protected]
> Signed-off-by: Bagas Sanjaya <[email protected]>
> ---
> 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
> ----------------------------------
> +=================================
Hmm... I can't really see any differences... What this patch seems to be
doing is to just change the markups for each level.
See, on Sphinx, the first markup (whatever it is) is level 1, level 2
the second different markup and so on.
So, before this patch, kernel-doc.rst had:
level 1: Writing kernel-doc comments
=====================================
level 2: How to format kernel-doc comments
------------------------------------------
level 3: Function parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
And after it, it will have:
====================================
level 1: Writing kernel-doc comments
====================================
level 2: How to format kernel-doc comments
==========================================
level 3: Function parameters
----------------------------
No semantic changes at all.
The only (eventual) value of a change like that would be to make the
levels more uniform, but IMO, it is not worth to apply a change like
that, as:
1. There are a lot other documents that don't use the more commonly
used level standard;
2. Making all .rst files to use the same definitions is hard;
3. Even if we place everything using identical markups for every
level, as new stuff gets added, different (still valid)
markups could be used on newer documents.
Regards,
Mauro
>
> 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::
Thanks,
Mauro
On 26/03/22 20.56, Mauro Carvalho Chehab wrote:
> Hmm... I can't really see any differences... What this patch seems to be
> doing is to just change the markups for each level.
>
> See, on Sphinx, the first markup (whatever it is) is level 1, level 2
> the second different markup and so on.
>
> So, before this patch, kernel-doc.rst had:
>
> level 1: Writing kernel-doc comments
> =====================================
>
> level 2: How to format kernel-doc comments
> ------------------------------------------
>
> level 3: Function parameters
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> And after it, it will have:
>
> ====================================
> level 1: Writing kernel-doc comments
> ====================================
>
> level 2: How to format kernel-doc comments
> ==========================================
>
> level 3: Function parameters
> ----------------------------
>
> No semantic changes at all.
>
> The only (eventual) value of a change like that would be to make the
> levels more uniform, but IMO, it is not worth to apply a change like
> that, as:
>
> 1. There are a lot other documents that don't use the more commonly
> used level standard;
>
> 2. Making all .rst files to use the same definitions is hard;
>
> 3. Even if we place everything using identical markups for every
> level, as new stuff gets added, different (still valid)
> markups could be used on newer documents.
>
> Regards,
> Mauro
>
Indeed, fixing heading levels when adding title heading is required because
without it, Sphinx will complain "indentation inconsistency" error.
Maybe better splitting indentation level changes into its own patch, right?
--
An old man doll... just what I always wanted! - Clara
Hello Bagas,
On Sun, 27 Mar 2022 12:27:20 +0700,
Bagas Sanjaya wrote:
> On 26/03/22 20.56, Mauro Carvalho Chehab wrote:
>> Hmm... I can't really see any differences... What this patch seems to be
>> doing is to just change the markups for each level.
>>
>> See, on Sphinx, the first markup (whatever it is) is level 1, level 2
>> the second different markup and so on.
>>
>> So, before this patch, kernel-doc.rst had:
>>
>> level 1: Writing kernel-doc comments
>> =====================================
>>
>> level 2: How to format kernel-doc comments
>> ------------------------------------------
>>
>> level 3: Function parameters
>> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>
>> And after it, it will have:
>>
>> ====================================
>> level 1: Writing kernel-doc comments
>> ====================================
>>
>> level 2: How to format kernel-doc comments
>> ==========================================
>>
>> level 3: Function parameters
>> ----------------------------
>>
>> No semantic changes at all.
>>
>> The only (eventual) value of a change like that would be to make the
>> levels more uniform, but IMO, it is not worth to apply a change like
>> that, as:
>>
>> 1. There are a lot other documents that don't use the more commonly
>> used level standard;
>>
>> 2. Making all .rst files to use the same definitions is hard;
>>
>> 3. Even if we place everything using identical markups for every
>> level, as new stuff gets added, different (still valid)
>> markups could be used on newer documents.
>>
>> Regards,
>> Mauro
>>
>
> Indeed, fixing heading levels when adding title heading is required because
> without it, Sphinx will complain "indentation inconsistency" error.
I think all you'd need to do would be to promote both of two headings
of
Title A
=======
to
=======
Title A
=======
, namely "Writing kernel-doc comments" and "Including kernel-doc
comments". They deserve their own chapters in PDF.
As Mauro says, such changes won't have any effect on the resulting
pretty-printed docs. So I'm afraid I don't see any point in 1/2.
Thanks, Akira
>
> Maybe better splitting indentation level changes into its own patch, right?
>