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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <49829de5-efe5-9065-d87a-2494d16b9465@gmail.com>
Date:   Sun, 27 Mar 2022 12:27:20 +0700
From:   Bagas Sanjaya <bagasdotme@...il.com>
To:     Mauro Carvalho Chehab <mchehab@...nel.org>
Cc:     linux-doc@...r.kernel.org, Jonathan Corbet <corbet@....net>,
        "David S. Miller" <davem@...emloft.net>,
        Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
        "Rafael J. Wysocki" <rafael.j.wysocki@...el.com>,
        Jens Axboe <axboe@...nel.dk>,
        Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
        Akira Yokosawa <akiyks@...il.com>, linux-kernel@...r.kernel.org
Subject: Re: [PATCH v2 1/2] Documentation: kernel-doc: Promote "Writing
 kernel-doc comments" to page title

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