Re: [PATCH V4 2/2] tools/perf: Add kernel-doc comment to auxtrace_record__init() function

[Namhyung Kim <namhyung@kernel.org>]

Hello,

On Sat, May 02, 2026 at 08:02:37PM +0530, Athira Rajeev wrote:
> Add documentation comment describing the parameters
> and return code for auxtrace_record__init() in util/auxtrace.c
> 
> Using "struct evlist *evlist __maybe_unused", gives below
> warning with "scripts/kernel-doc".
> 
>  # ./scripts/kernel-doc -none tools/perf/util/auxtrace.c
>  Warning: tools/perf/util/auxtrace.c:912 function parameter '__maybe_unused' not described in 'auxtrace_record__init'
>  Warning: tools/perf/util/auxtrace.c:912 function parameter '__maybe_unused' not described in 'auxtrace_record__init'
> 
> Updated  parameter as "struct evlist __maybe_unused *evlist"
> With the change, there is no erros/warnings with kernel-doc

Hmm.. this is not what we used to have.  I'm not sure if we want to
update them all.  Maybe better to leave it for now.

> 
> Signed-off-by: Athira Rajeev <atrajeev@linux.ibm.com>
> ---
> Changelog:
> v3 -> v4:
> Addressed review comment from Sashiko:
> Update return value expectation for fail as
> non zero return err code.
> 
> v2 -> v3:
> Addressed review comment from Sashiko:
> Update return value expectation for success and fail
> correctly.
> 
>  tools/perf/util/auxtrace.c | 17 ++++++++++++++++-
>  1 file changed, 16 insertions(+), 1 deletion(-)
> 
> diff --git a/tools/perf/util/auxtrace.c b/tools/perf/util/auxtrace.c
> index a224687ffbc1..9e11cf4299b8 100644
> --- a/tools/perf/util/auxtrace.c
> +++ b/tools/perf/util/auxtrace.c
> @@ -896,8 +896,23 @@ int auxtrace_parse_aux_action(struct evlist *evlist)
>  	return 0;
>  }
>  
> +/**
> + * auxtrace_record__init - Initialize an AUX area tracing record.
> + * @evlist: The list of events to check for AUX area tracing event.
> + * @err: Pointer to an integer to store return code.
> + *
> + * This function looks through the @evlist to determine which AUX area
> + * tracing hardware is being used and initializes the auxtrace_record
> + * structure.
> + *
> + * Return:
> + * a) A pointer to the struct auxtrace_record on success.

I think you should mention that the this function should set *err to
zero on success.

Thanks,
Namhyung


> + * b) NULL with @err = 0 if no AUX area tracing event is found/supported
> + *    (not considered an error).
> + * c) NULL with non-zero @err on actual auxtrace_record__init failure.
> + */
>  struct auxtrace_record *__weak
> -auxtrace_record__init(struct evlist *evlist __maybe_unused, int *err)
> +auxtrace_record__init(struct evlist __maybe_unused *evlist, int *err)
>  {
>  	*err = 0;
>  	return NULL;
> -- 
> 2.47.3
>