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

[Bagas Sanjaya]

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