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

[Gustavo Sousa]

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

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.


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