linux-kernel - Re: [PATCH v5 35/52] 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: <20201006191953.GA3598358@gmail.com>
Date:   Tue, 6 Oct 2020 12:19:53 -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 v5 35/52] docs: fs: fscrypt.rst: get rid of :c:type: tags

On Tue, Oct 06, 2020 at 04:03:32PM +0200, Mauro Carvalho Chehab wrote:
> 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.

I tried 'make htmldocs' before and after your patchset ("sphinx3-fixes-v5").
Before, all the struct fscrypt_* are rendered in code font.  After, they are
rendered in the regular text font.  Is that really working as intended?

> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
> ---
>  Documentation/filesystems/fscrypt.rst | 51 ++++++++++++---------------
>  1 file changed, 23 insertions(+), 28 deletions(-)
> 

Why are the changes to fscrypt.rst split between two patches,

	docs: get rid of :c:type explicit declarations for structs

and

	docs: fs: fscrypt.rst: get rid of :c:type: tags

?  They're the same type of changes.  The first just removes half the :c:type:
tags, and the second removes the rest.  Shouldn't it be one patch?

> diff --git a/Documentation/filesystems/fscrypt.rst b/Documentation/filesystems/fscrypt.rst
> index 4f858b38a412..46a9d1bd2ab5 100644
> --- a/Documentation/filesystems/fscrypt.rst
> +++ b/Documentation/filesystems/fscrypt.rst
> @@ -437,8 +437,7 @@ FS_IOC_SET_ENCRYPTION_POLICY
>  The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an
>  empty directory or verifies that a directory or regular file already
>  has the specified encryption policy.  It takes in a pointer to a
> -struct fscrypt_policy_v1 or a :c:type:`struct
> -fscrypt_policy_v2`, defined as follows::
> +struct fscrypt_policy_v1 or a struct fscrypt_policy_v2, defined as follows::
[...]
>  If the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY
>  verifies that the file is an empty directory.  If so, the specified
> @@ -637,9 +634,8 @@ The FS_IOC_GET_ENCRYPTION_POLICY ioctl can also retrieve the
>  encryption policy, if any, for a directory or regular file.  However,
>  unlike `FS_IOC_GET_ENCRYPTION_POLICY_EX`_,
>  FS_IOC_GET_ENCRYPTION_POLICY only supports the original policy
> -version.  It takes in a pointer directly to a :c:type:`struct
> -fscrypt_policy_v1` rather than a :c:type:`struct
> -fscrypt_get_policy_ex_arg`.
> +version.  It takes in a pointer directly to struct fscrypt_policy_v1
> +rather than struct fscrypt_get_policy_ex_arg.

In some cases you deleted the "a" in "a struct" but in other cases you didn't.
Intentional?  It seems the file should consistently use one style or the other.

Also please use textwidth=70 for consistency with the rest of the file.

- Eric