linux-kernel - Re: [PATCH v6 35/80] docs: fs: fscrypt.rst: get rid of :c:type: tags

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: <20201014215954.GB2545693@gmail.com>
Date:   Wed, 14 Oct 2020 14:59:54 -0700
From:   Eric Biggers <ebiggers@...nel.org>
To:     Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
Cc:     Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        "Jonathan Corbet" <corbet@....net>,
        "Theodore Y. Ts'o" <tytso@....edu>,
        Jaegeuk Kim <jaegeuk@...nel.org>,
        linux-fscrypt@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [PATCH v6 35/80] docs: fs: fscrypt.rst: get rid of :c:type: tags

On Wed, Oct 14, 2020 at 08:59:07AM +0200, Mauro Carvalho Chehab wrote:
> [PATCH v6.1 35/80] docs: fs: fscrypt.rst: get rid of :c:type: tags
> 
> The :c:type: tag has problems with Sphinx 3.x, as structs
> there should be declared with c:struct.
> 
> So, remove them, relying at automarkup.py extension to
> convert them into cross-references.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>

"relying at" => "relying on".

Otherwise looks fine, you can add:

Reviewed-by: Eric Biggers <ebiggers@...gle.com>

I do still wonder about your comment though:

> It should be said that, currently, if there's no documentation for "foo",
> automarkup will just keep using the regular text font, keeping the text
> untouched.

That will apply to most (maybe all) of the structures mentioned in this file.
I expected that if the documentation system now automatically recognizes
'struct foo', then it would render it in code font even when 'struct foo' isn't
documented.  Any particular reason why that isn't the case?  Not like I care
much myself, but it's a bit unexpected and it means this change actually makes
the rendered documentation look worse...

- Eric