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

From: Eric Biggers
Date: Wed Oct 14 2020 - 18:00:05 EST


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@xxxxxxxxxx>

"relying at" => "relying on".

Otherwise looks fine, you can add:

Reviewed-by: Eric Biggers <ebiggers@xxxxxxxxxx>

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