[PATCH] ipc/sem: fix malformed kernel-doc comment

[PATCH] ipc/sem: fix malformed kernel-doc comment

[Alexander Lechthaler]

perform_atomic_semop[_slow]() uses unsupported kernel-doc syntax,
triggering a warning:

  This comment starts with '/**', but isn't a kernel-doc comment

Split the shared comment into separate kernel-doc blocks for
perform_atomic_semop() and perform_atomic_semop_slow().

No functional change.

Signed-off-by: Alexander Lechthaler <alexander@lechthaler.online>
---
 ipc/sem.c | 21 +++++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

diff --git a/ipc/sem.c b/ipc/sem.c
index 6cdf862b1f5c..fde2bcc225dc 100644
--- a/ipc/sem.c
+++ b/ipc/sem.c
@@ -627,8 +627,8 @@ SYSCALL_DEFINE3(semget, key_t, key, int, nsems, int, semflg)
 }
 
 /**
- * perform_atomic_semop[_slow] - Attempt to perform semaphore
- *                               operations on a given array.
+ * perform_atomic_semop_slow - Attempt to perform semaphore
+ *                             operations on a given array.
  * @sma: semaphore array
  * @q: struct sem_queue that describes the operation
  *
@@ -716,6 +716,23 @@ static int perform_atomic_semop_slow(struct sem_array *sma, struct sem_queue *q)
 	return result;
 }
 
+/**
+ * perform_atomic_semop - Attempt to perform semaphore
+ *                        operations on a given array.
+ * @sma: semaphore array
+ * @q: struct sem_queue that describes the operation
+ *
+ * Caller blocking are as follows, based the value
+ * indicated by the semaphore operation (sem_op):
+ *
+ *  (1) >0 never blocks.
+ *  (2)  0 (wait-for-zero operation): semval is non-zero.
+ *  (3) <0 attempting to decrement semval to a value smaller than zero.
+ *
+ * Returns 0 if the operation was possible.
+ * Returns 1 if the operation is impossible, the caller must sleep.
+ * Returns <0 for error codes.
+ */
 static int perform_atomic_semop(struct sem_array *sma, struct sem_queue *q)
 {
 	int result, sem_op, nsops;
-- 
2.43.0

Re: [PATCH] ipc/sem: fix malformed kernel-doc comment

[Lorenzo Stoakes]

+cc Jon, Shuah from documentation side

On Fri, May 22, 2026 at 09:05:07PM +0200, Alexander Lechthaler wrote:
> perform_atomic_semop[_slow]() uses unsupported kernel-doc syntax,
> triggering a warning:
>
>   This comment starts with '/**', but isn't a kernel-doc comment
>
> Split the shared comment into separate kernel-doc blocks for
> perform_atomic_semop() and perform_atomic_semop_slow().
>
> No functional change.
>
> Signed-off-by: Alexander Lechthaler <alexander@lechthaler.online>

This LGTM, though I wonder if that 'Returns' syntax is right. But either way
seems fine so:

Acked-by: Lorenzo Stoakes <ljs@kernel.org>

> ---
>  ipc/sem.c | 21 +++++++++++++++++++--
>  1 file changed, 19 insertions(+), 2 deletions(-)
>
> diff --git a/ipc/sem.c b/ipc/sem.c
> index 6cdf862b1f5c..fde2bcc225dc 100644
> --- a/ipc/sem.c
> +++ b/ipc/sem.c
> @@ -627,8 +627,8 @@ SYSCALL_DEFINE3(semget, key_t, key, int, nsems, int, semflg)
>  }
>
>  /**
> - * perform_atomic_semop[_slow] - Attempt to perform semaphore
> - *                               operations on a given array.
> + * perform_atomic_semop_slow - Attempt to perform semaphore
> + *                             operations on a given array.
>   * @sma: semaphore array
>   * @q: struct sem_queue that describes the operation
>   *
> @@ -716,6 +716,23 @@ static int perform_atomic_semop_slow(struct sem_array *sma, struct sem_queue *q)
>  	return result;
>  }
>
> +/**
> + * perform_atomic_semop - Attempt to perform semaphore
> + *                        operations on a given array.
> + * @sma: semaphore array
> + * @q: struct sem_queue that describes the operation
> + *
> + * Caller blocking are as follows, based the value
> + * indicated by the semaphore operation (sem_op):
> + *
> + *  (1) >0 never blocks.
> + *  (2)  0 (wait-for-zero operation): semval is non-zero.
> + *  (3) <0 attempting to decrement semval to a value smaller than zero.
> + *
> + * Returns 0 if the operation was possible.
> + * Returns 1 if the operation is impossible, the caller must sleep.
> + * Returns <0 for error codes.
> + */
>  static int perform_atomic_semop(struct sem_array *sma, struct sem_queue *q)
>  {
>  	int result, sem_op, nsops;
> --
> 2.43.0
>