Re: [Intel-xe] [PATCH] drm/xe: Fix kernel doc warning for PMU events

[Aravind Iddamsetty <aravind.iddamsetty@linux.intel.com>]

On 20/09/23 18:51, Gustavo Sousa wrote:
> Quoting Aravind Iddamsetty (2023-09-20 05:26:56-03:00)
>> On 19/09/23 18:57, Gustavo Sousa wrote:
>>> Quoting Aravind Iddamsetty (2023-09-19 03:36:11-03:00)
>>>> Add DOC keyword to PMU events comment in include/drm/xe_drm.h to make it
>>>> kernel doc format.
>>>>
>>>> Fixes: 4a9681392cec ("drm/xe/pmu: Enable PMU interface")
>>>>
>>>> Signed-off-by: Aravind Iddamsetty <aravind.iddamsetty@linux.intel.com>
>>>> ---
>>>> include/uapi/drm/xe_drm.h | 2 +-
>>>> 1 file changed, 1 insertion(+), 1 deletion(-)
>>>>
>>>> diff --git a/include/uapi/drm/xe_drm.h b/include/uapi/drm/xe_drm.h
>>>> index 63863eda8355..6ab85c7fed36 100644
>>>> --- a/include/uapi/drm/xe_drm.h
>>>> +++ b/include/uapi/drm/xe_drm.h
>>>> @@ -1054,7 +1054,7 @@ struct drm_xe_vm_madvise {
>>>> };
>>>>
>>>> /**
>>>> - * XE PMU event config IDs
>>>> + * DOC: XE PMU event config IDs
>>> That was my first thought when writing [1], but then I realized that the
>>> XE_PMU_*() macros would not show up in the generated documentation.
>>> Not sure if there is a special kernel-doc syntax to make them appear
>>> there. Maybe we should just list them in this kernel-doc?
>> IIUC as per Documentation/doc-guide/kernel-doc.rst it allows
>> for source code comments and code itself can't be part of the comment
>> so I don't think we need to list the defines in the comment.
> But then the generated HTML will not contain the ids we refer by "these ID's".
> If we are not going to list them, maybe change the wording to help the user
> locate them in the header file? Otherwise, I'm not sure it would make much sense
> to keep this as a kernel-doc.
ok will update the comment accordingly
>
> By the way, I built the docs locally and there is an issue with the code block:
>
>     (...)/Documentation/gpu/driver-uapi:24: ./include/uapi/drm/xe_drm.h:1063: ERROR: Error in "code-block" directive:
>     maximum 1 argument(s) allowed, 13 supplied.
>
> It just needs a line break after the code-block directive.

thanks for letting me know will fix this.

Regards,
Aravind.
>
>
> Gustavo Sousa
>
>>
>> Thanks,
>> Aravind.
>>> [1] https://patchwork.freedesktop.org/series/123887/
>>>
>>>>  *
>>>>  * Check 'man perf_event_open' to use these ID's in 'struct perf_event_attr'
>>>>  * as part of perf_event_open syscall to read a particular event.
>>>> -- 
>>>> 2.25.1
>>>>