Re: [LTP] [PATCH v2 2/2] syscalls/statx: Add docparse formatting

[Cyril Hrubis <chrubis@suse.cz>]

On Tue, Nov 30, 2021 at 03:11:13PM +0800, Yang Xu wrote:
> Signed-off-by: Yang Xu <xuyang2018.jy@fujitsu.com>
> ---
>  testcases/kernel/syscalls/statx/statx01.c | 31 +++++++++------------
>  testcases/kernel/syscalls/statx/statx02.c | 12 +++++----
>  testcases/kernel/syscalls/statx/statx03.c | 26 +++++++-----------
>  testcases/kernel/syscalls/statx/statx05.c |  8 +++---
>  testcases/kernel/syscalls/statx/statx06.c | 33 +++++++----------------
>  testcases/kernel/syscalls/statx/statx07.c | 21 ++++++++-------
>  6 files changed, 53 insertions(+), 78 deletions(-)
> 
> diff --git a/testcases/kernel/syscalls/statx/statx01.c b/testcases/kernel/syscalls/statx/statx01.c
> index 524acd273..b52bb2988 100644
> --- a/testcases/kernel/syscalls/statx/statx01.c
> +++ b/testcases/kernel/syscalls/statx/statx01.c
> @@ -4,35 +4,28 @@
>   * Email: code@zilogic.com
>   */
>  
> -/*
> - * Test statx
> +/*\
> + * [Description]
>   *
>   * This code tests the functionality of statx system call.
>   *
>   * TESTCASE 1:

Can we drop the TESTCASE 1: here and TESTCASE 2: below?

The rendered documentation looks better without these two.

>   * The metadata for normal file are tested against predefined values:
                                                        ^
							expected?

predefined sounds strange a bit strange.

> - * 1) gid
> - * 2) uid
> - * 3) mode
> - * 4) blocks
> - * 5) size
> - * 6) nlink
> - * 7) mnt_id
>   *
> - * A file is created and metadata values are set with
> - * predefined values.
> - * Then the values obtained using statx is checked against
> - * the predefined values.
> + * - gid
> + * - uid
> + * - mode
> + * - blocks
> + * - size
> + * - nlink
> + * - mnt_id
>   *
>   * TESTCASE 2:
>   * The metadata for device file are tested against predefined values:
> - * 1) MAJOR number
> - * 2) MINOR number
>   *
> - * A device file is created seperately using mknod(must be a root user).
> - * The major number and minor number are set while creation.
> - * Major and minor numbers obtained using statx is checked against
> - * predefined values.
> + * - MAJOR number
> + * - MINOR number
> + *
>   * Minimum kernel version required is 4.11.

We do have min_kver in the tst_test structure and it's in the parsed
metadata as well, so I wouldn't repeat it here.

>   */
>  
> diff --git a/testcases/kernel/syscalls/statx/statx02.c b/testcases/kernel/syscalls/statx/statx02.c
> index 63133a3b7..56577599c 100644
> --- a/testcases/kernel/syscalls/statx/statx02.c
> +++ b/testcases/kernel/syscalls/statx/statx02.c
> @@ -4,12 +4,13 @@
>   * Email: code@zilogic.com
>   */
>  
> -/*
> - * Test statx
> +/*\
> + * [Description]
> + *
> + * This code tests the following flags with statx syscall:
>   *
> - * This code tests the following flags:
> - * 1) AT_EMPTY_PATH
> - * 2) AT_SYMLINK_NOFOLLOW
> + * - AT_EMPTY_PATH
> + * - AT_SYMLINK_NOFOLLOW
>   *
>   * A test file and a link for it is created.
>   *
> @@ -19,6 +20,7 @@
>   * To check symlink no follow flag, the linkname is statxed.
>   * To ensure that link is not dereferenced, obtained inode is compared
>   * with test file inode.
> + *
>   * Minimum kernel version required is 4.11.

Here as well no need to repeat the minimal kernel version.

>   */
>  
> diff --git a/testcases/kernel/syscalls/statx/statx03.c b/testcases/kernel/syscalls/statx/statx03.c
> index c72d7fead..de2fe4d38 100644
> --- a/testcases/kernel/syscalls/statx/statx03.c
> +++ b/testcases/kernel/syscalls/statx/statx03.c
> @@ -4,25 +4,17 @@
>   * Email: code@zilogic.com
>   */
>  
> -/*
> - * Test statx
> +/*\
> + * [Description]
>   *
> - * This code tests if expected error values are returned for specific cases by
> - * statx.
> - * The error cases are simulated and the return value is checked against
> - * expected error number value.
> - * The following error values are tested:
> - * 1) EBADF - Bad file descriptor
> - * 2) EFAULT - Bad address
> - * 3) EINVAL - Invalid argument
> - * 4) ENOENT - No such file or directory
> - * 5) ENOTDIR - Not a directory
> - * 6) ENAMETOOLONG - Filename too long
> + * Test basic error handling of statx syscall:
>   *
> - * Error scenario is simulated for each listed flag by passing
> - * respective arguments.
> - * The obtained error flag is checked against the expected
> - * flag value for that scenario.
> + * - EBADF - Bad file descriptor
> + * - EFAULT - Bad address
> + * - EINVAL - Invalid argument
> + * - ENOENT - No such file or directory
> + * - ENOTDIR - Not a directory
> + * - ENAMETOOLONG - Filename too long
>   *
>   * Minimum Kernel version required is 4.11.

Here as well.

>   */
> diff --git a/testcases/kernel/syscalls/statx/statx05.c b/testcases/kernel/syscalls/statx/statx05.c
> index 81a5bcbf2..83c6c3ab5 100644
> --- a/testcases/kernel/syscalls/statx/statx05.c
> +++ b/testcases/kernel/syscalls/statx/statx05.c
> @@ -4,10 +4,12 @@
>   * Email: code@zilogic.com
>   */
>  
> -/*
> - * Test statx
> +/*\
> + * [Description]
> + *
> + * Test statx syscall with STATX_ATTR_ENCRYPTED flag
>   *
> - * 1) STATX_ATTR_ENCRYPTED - A key is required for the file to be encrypted by
> + * - STATX_ATTR_ENCRYPTEDL: A key is required for the file to be encrypted by
>   *                          the filesystem.

The list with single entry looks strange here. I would rewrite it as:

Test statx syscall with STATX_ATTR_ENCRYPTED flag, if set a key is
required for the file to be encrypted by the filesystem.

>   * e4crypt is used to set the encrypt flag (currently supported only by ext4).

And here as well, no need to repeat the minimal kernel version.

> diff --git a/testcases/kernel/syscalls/statx/statx06.c b/testcases/kernel/syscalls/statx/statx06.c
> index 0469d66c5..4a0685a65 100644
> --- a/testcases/kernel/syscalls/statx/statx06.c
> +++ b/testcases/kernel/syscalls/statx/statx06.c
> @@ -1,36 +1,21 @@
>  // SPDX-License-Identifier: GPL-2.0 or later
>  /*
> - *  Copyright (c) Zilogic Systems Pvt. Ltd., 2018
> - *  Email : code@zilogic.com
> + * Copyright (c) Zilogic Systems Pvt. Ltd., 2018
> + * Email : code@zilogic.com
>   */
>  
> -/*
> - * DESCRIPTION :
> +/*\
> + * [Description]
>   *
> - * Test-Case 1 : Testing btime
> - * flow :       The time before and after the execution of the create
> - *              system call is noted.
> - *		It is checked whether the birth time returned by statx lies in
> - *              this range.
> + * Test the following file timestamps of statx syscall:
>   *
> - * Test-Case 2 : Testing mtime
> - * flow :       The time before and after the execution of the write
> - *              system call is noted.
> - *              It is checked whether the modification time returned
> - *              by statx lies in this range.
> + * - btime - The time before and after the execution of the create system call is noted.
>   *
> - * Test-Case 3 : Testing atime
> - * flow :       The time before and after the execution of the read
> - *              system call is noted.
> - *              It is checked whether the access time returned by statx lies in
> - *              this range.
> + * - mtime - The time before and after the execution of the write system call is noted.
>   *
> - * Test-Case 4 : Testing ctime
> - * flow :	The time before and after the execution of the chmod
> - *              system call is noted.
> - *              It is checked whether the status change time returned by statx
> - *              lies in this range.
> + * - atime - The time before and after the execution of the read system call is noted.
>   *
> + * - ctime - The time before and after the execution of the chmod system call is noted.
>   */
>  
>  #define _GNU_SOURCE
> diff --git a/testcases/kernel/syscalls/statx/statx07.c b/testcases/kernel/syscalls/statx/statx07.c
> index ec1cdd190..e7045edaa 100644
> --- a/testcases/kernel/syscalls/statx/statx07.c
> +++ b/testcases/kernel/syscalls/statx/statx07.c
> @@ -1,15 +1,16 @@
>  // SPDX-License-Identifier: GPL-2.0-or-later
>  /*
> - *  Copyright (c) Zilogic Systems Pvt. Ltd., 2018
> - *  Email : code@zilogic.com
> + * Copyright (c) Zilogic Systems Pvt. Ltd., 2018
> + * Email : code@zilogic.com
>   */
>  
> -/*
> - * Test statx
> +/*\
> + * [Description]
>   *
>   * This code tests the following flags:
> - * 1) AT_STATX_FORCE_SYNC
> - * 2) AT_STATX_DONT_SYNC
> + *
> + * - AT_STATX_FORCE_SYNC
> + * - AT_STATX_DONT_SYNC
>   *
>   * By exportfs cmd creating NFS setup.
>   *
> @@ -29,11 +30,11 @@
>   *
>   * The support for SYNC flags was implemented in NFS in:
>   *
> - * commit 9ccee940bd5b766b6dab6c1a80908b9490a4850d
> - * Author: Trond Myklebust <trond.myklebust@primarydata.com>
> - * Date:   Thu Jan 4 17:46:09 2018 -0500
> + *  commit 9ccee940bd5b766b6dab6c1a80908b9490a4850d
> + *  Author: Trond Myklebust <trond.myklebust@primarydata.com>
> + *  Date:   Thu Jan 4 17:46:09 2018 -0500
>   *
> - *     Support statx() mask and query flags parameters
> + *  Support statx() mask and query flags parameters
>   *
>   * Hence we skip the test on anything older than 4.16.

Here as well, no need to repeat the minimal kernel version.

> */
> -- 
> 2.23.0
> 
> 
> -- 
> Mailing list info: https://lists.linux.it/listinfo/ltp

-- 
Cyril Hrubis
chrubis@suse.cz

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp