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

[Athira Rajeev <atrajeev@linux.ibm.com>]

> On 4 May 2026, at 7:16 AM, Namhyung Kim <namhyung@kernel.org> wrote:
> 
> 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.

Sure, I will keep it as original version.

> 
>> 
>> 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.
Sure, I will update this 

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