[LTP] [PATCH] kcmp: Convert docs to docparse

[LTP] [PATCH] kcmp: Convert docs to docparse

[Ma Xinjian via ltp]

+ update copyright

Signed-off-by: Ma Xinjian <maxj.fnst@fujitsu.com>
---
 testcases/kernel/syscalls/kcmp/kcmp01.c | 16 ++++++++++------
 testcases/kernel/syscalls/kcmp/kcmp02.c | 20 ++++++++++++--------
 testcases/kernel/syscalls/kcmp/kcmp03.c | 17 +++++++++--------
 3 files changed, 31 insertions(+), 22 deletions(-)

diff --git a/testcases/kernel/syscalls/kcmp/kcmp01.c b/testcases/kernel/syscalls/kcmp/kcmp01.c
index 0e7cc7a22..c91c34d44 100644
--- a/testcases/kernel/syscalls/kcmp/kcmp01.c
+++ b/testcases/kernel/syscalls/kcmp/kcmp01.c
@@ -1,14 +1,18 @@
 // SPDX-License-Identifier: GPL-2.0-or-later
 /*
  * Copyright (c) 2015 Cedric Hnyda <chnyda@suse.com>
+ * Copyright (c) Linux Test Project, 2015-2024
  */
 
- /* Description:
- *   Verify that:
- *		1) kcmp returns 0 with two process and two fd refering to the
- *			same open file
- *		2) kcmp doesn't return 0 with two process and two fd not
- *		   refering to the same open file
+/*\
+ * [Description]
+ *
+ * Verify that
+ *
+ * 1. kcmp() returns 0 with two process and two fd refering to the same
+ * open file
+ * 2. kcmp() doesn't return 0 with two process and two fd not refering
+ * to the same open file
  */
 
 #define _GNU_SOURCE
diff --git a/testcases/kernel/syscalls/kcmp/kcmp02.c b/testcases/kernel/syscalls/kcmp/kcmp02.c
index 076b4a723..eae8bb9cc 100644
--- a/testcases/kernel/syscalls/kcmp/kcmp02.c
+++ b/testcases/kernel/syscalls/kcmp/kcmp02.c
@@ -1,16 +1,20 @@
 // SPDX-License-Identifier: GPL-2.0-or-later
 /*
  * Copyright (c) 2015 Cedric Hnyda <chnyda@suse.com>
+ * Copyright (c) Linux Test Project, 2015-2024
  */
 
- /* Description:
- *   Verify that:
- *		1) kcmp fails with bad pid
- *		2) kcmp fails with invalid flag
- *		3) kcmp fails with invalid flag
- *		4) kcmp fails with invalid flag
- *		5) kcmp fails with invalid flag
- *		6) kcmp fails with invalid fd
+/*\
+ * [Description]
+ *
+ * Verify that, kcmp() returns -1 and sets errno to
+ *
+ * 1. ESRCH if pid does not exist
+ * 2. EINVAL if type is invalid
+ * 3. EINVAL if type is invalid
+ * 4. EINVAL if type is invalid
+ * 5. EINVAL if type is invalid
+ * 6. EBADF if fd is invalid
  */
 
 #define _GNU_SOURCE
diff --git a/testcases/kernel/syscalls/kcmp/kcmp03.c b/testcases/kernel/syscalls/kcmp/kcmp03.c
index 7af5cb150..4ae6e0295 100644
--- a/testcases/kernel/syscalls/kcmp/kcmp03.c
+++ b/testcases/kernel/syscalls/kcmp/kcmp03.c
@@ -1,17 +1,18 @@
 // SPDX-License-Identifier: GPL-2.0-or-later
 /*
  * Copyright (c) 2016 Xiao Yang <yangx.jy@cn.fujitsu.com>
+ * Copyright (c) Linux Test Project, 2016-2024
  */
 
- /*
- * Testname: kcmp03.c
+/*\
+ * [Description]
  *
- * Description:
- * 1) kcmp() returns 0 if the processes share the same file system information.
- * 2) kcmp() returns 0 if the processes share I/O context.
- * 3) kcmp() returns 0 if the processes share the same list of System V
- *    semaphore undo operations.
- * 4) kcmp() returns 0 if the processes share the same address space.
+ * Verify that, kcmp() returns 0 if the processes
+ *
+ * 1. share the same file system information
+ * 2. share I/O context
+ * 3. share the same list of System V semaphore undo operations
+ * 4. share the same address space
  */
 
 #define _GNU_SOURCE
-- 
2.42.0


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

Re: [LTP] [PATCH] kcmp: Convert docs to docparse

[Petr Vorel]

Hi Ma,

> +++ b/testcases/kernel/syscalls/kcmp/kcmp02.c
...
> - /* Description:
> - *   Verify that:
> - *		1) kcmp fails with bad pid
> - *		2) kcmp fails with invalid flag
> - *		3) kcmp fails with invalid flag
> - *		4) kcmp fails with invalid flag
> - *		5) kcmp fails with invalid flag
> - *		6) kcmp fails with invalid fd
> +/*\
> + * [Description]
> + *
> + * Verify that, kcmp() returns -1 and sets errno to
> + *
> + * 1. ESRCH if pid does not exist
> + * 2. EINVAL if type is invalid
> + * 3. EINVAL if type is invalid
> + * 4. EINVAL if type is invalid
> + * 5. EINVAL if type is invalid
4x EINVAL, it would be better to describe how they differs.
Obviously KCMP_TYPES (the last item in enum kcmp_type in
include/uapi/linux/kcmp.h) should not be used in userspace (it's not in man
page). Other wrong values are -1 (negative), INT_MIN (negative) and INT_MAX too high.

Or, if you don't want to bother with the description, you could wrote:

* 1. ESRCH if pid does not exist
* 2-5. EINVAL if type is invalid
* 5. EINVAL if type is invalid
* 6. EBADF if fd is invalid

Kind regards,
Petr

> + * 6. EBADF if fd is invalid
...

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

Re: [LTP] [PATCH] kcmp: Convert docs to docparse

[Xinjian Ma (Fujitsu) via ltp]

Hi Petr

> Hi Ma,
> 
> > +++ b/testcases/kernel/syscalls/kcmp/kcmp02.c
> ...
> > - /* Description:
> > - *   Verify that:
> > - *		1) kcmp fails with bad pid
> > - *		2) kcmp fails with invalid flag
> > - *		3) kcmp fails with invalid flag
> > - *		4) kcmp fails with invalid flag
> > - *		5) kcmp fails with invalid flag
> > - *		6) kcmp fails with invalid fd
> > +/*\
> > + * [Description]
> > + *
> > + * Verify that, kcmp() returns -1 and sets errno to
> > + *
> > + * 1. ESRCH if pid does not exist
> > + * 2. EINVAL if type is invalid
> > + * 3. EINVAL if type is invalid
> > + * 4. EINVAL if type is invalid
> > + * 5. EINVAL if type is invalid
> 4x EINVAL, it would be better to describe how they differs.
> Obviously KCMP_TYPES (the last item in enum kcmp_type in
> include/uapi/linux/kcmp.h) should not be used in userspace (it's not in man page).
> Other wrong values are -1 (negative), INT_MIN (negative) and INT_MAX too
> high.

Thanks for the review, I have sent the PATCH v2, PTAL.

Best regards,
Ma
> 
> Or, if you don't want to bother with the description, you could wrote:
> 
> * 1. ESRCH if pid does not exist
> * 2-5. EINVAL if type is invalid
> * 5. EINVAL if type is invalid
> * 6. EBADF if fd is invalid
> 
> Kind regards,
> Petr
> 
> > + * 6. EBADF if fd is invalid
> ...

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