Re: [PATCH v2 1/2] Documentation: kernel-doc: Promote "Writing kernel-doc comments" to page title

[Akira Yokosawa <akiyks@gmail.com>]

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?
>