lkml.org 
[lkml]   [2022]   [Mar]   [27]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
SubjectRe: [PATCH v2 1/2] Documentation: kernel-doc: Promote "Writing kernel-doc comments" to page title
From
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

\
 
 \ /
  Last update: 2022-03-27 07:28    [W:0.037 / U:0.312 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site