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

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