Re: [PATCH 1/5] drm/xe/debugfs: Update xe_gt_topology_dump signature

[Michal Wajdeczko <michal.wajdeczko@intel.com>]

On 9/30/2025 7:23 PM, Raag Jadav wrote:
> On Tue, Sep 30, 2025 at 02:43:47PM +0300, Jani Nikula wrote:
>> On Tue, 30 Sep 2025, Michal Wajdeczko <michal.wajdeczko@intel.com> wrote:
>>> On 9/30/2025 10:45 AM, Jani Nikula wrote:
>>>> On Tue, 23 Sep 2025, Michal Wajdeczko <michal.wajdeczko@intel.com> wrote:
>>>>> +/**
>>>>> + * xe_gt_topology_dump() - Dump GT topology into a drm printer.
>>>>> + * @gt: the &xe_gt
>>>>> + * @p: the &drm_printer
>>>>> + *
>>>>> + * Return: always 0.
>>>>> + */
>>>>> +int xe_gt_topology_dump(struct xe_gt *gt, struct drm_printer *p)
>>>>
>>>> What benefit do the formatted kernel-doc give us? IMO it's just
>>>> boilerplate with pretty much everything being obvious from the function
>>>> name and parameters. And the functions aren't significant enough to be
>>>> made part of the Sphinx build either.
>>>
>>> I'm just following the (unwritten?) rule that in Xe we should document
>>> all public functions, and while in some cases such kernel-doc does not
>>> bring anything new, also like in [1], IMO it's still better than no
>>> documentation at all, as sometimes, like [2], function name isn't
>>> telling you the whole thing
>>
>> I'm not arguing against documentation. I'm arguing against excessive use
>> of kernel-doc formatting for functions that will never be part of the
>> Sphinx documentation build.
>>
>> /**
>>  * xe_gt_topology_dump() - Dump GT topology into a drm printer.
>>  * @gt: the &xe_gt
>>  * @p: the &drm_printer
>>  *
>>  * Return: always 0.
>>  */
>>
>> vs.
>>
>> /* Dump GT topology into a drm printer. Always returns 0. */
>>
>> For non-EXPORT_SYMBOL() driver internal stuff, in most cases the
>> parameter descriptions are self-evident, and repeating the function name
>> is just, well, repeating. The formatting doesn't buy us anything, it
>> just brings overhead and extra maintenance, because the format will be
>> checked.
>>
>> For EXPORT_SYMBOL() and the more important functions, or generally
>> things you might want to include in the Sphinx build, or anything that
>> might benefit from the formatting for readability, sure, use
>> kernel-doc. Otherwise, I wouldn't bother.
> 
> +1. I've always thought kdoc formatting was a general guidance than a hard
> rule, especially when the driver footprint is already quite huge.
> 

I would not mess here with the driver footprint, as this is not the same as LOC

what I'm afraid is that once we decide to relax the documentation rule,
then suddenly all functions will be treated by their authors as "trivial"
and as such do not require *any* doc at all, even the simplified variant

OTOH if adding few lines with @params is too much too much for the author,
then maybe he will reconsider if function really must be public and/or
requires that many parameters, and/or their names makes sense