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

[sashiko-bot@kernel.org]

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Low] The added kernel-doc comment incorrectly documents a NULL return value as strictly a failure, which contradicts the actual API behavior and the implementation directly below it.
--

commit 32a1e931b50aecc6b395f4170e1b7ccb2ad1db6c
Author: Athira Rajeev <atrajeev@linux.ibm.com>

tools/perf: Add kernel-doc comment to auxtrace_record__init() function

This commit adds a kernel-doc comment for auxtrace_record__init() to
describe its parameters and return value. It also rearranges the
__maybe_unused attribute to fix a kernel-doc warning.

> diff --git a/tools/perf/util/auxtrace.c b/tools/perf/util/auxtrace.c
> --- a/tools/perf/util/auxtrace.c
> +++ b/tools/perf/util/auxtrace.c

[ ... ]

> +/**
> + * 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 pointer to the struct auxtrace_record on success, or NULL on
> + * failure (@err needs to be set).
> + */
>  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;
>  }

Does this kernel-doc comment accurately describe the return value
expectations?

The weak implementation of auxtrace_record__init() directly below this
comment returns NULL and sets *err = 0. Returning NULL with a zero error
code appears to be the designated success path to indicate that no AUX area
tracing hardware is available, rather than a failure.

Could the documentation be updated to reflect that returning NULL with
*err = 0 is a valid success condition?

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20260501145436.1327-1-atrajeev@linux.ibm.com?part=2