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

[Bagas Sanjaya <bagasdotme@gmail.com>]

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