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

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

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

[1] https://elixir.bootlin.com/linux/v6.17-rc3/source/drivers/gpu/drm/xe/xe_bo.h#L239
[2] https://elixir.bootlin.com/linux/v6.17-rc3/source/drivers/gpu/drm/xe/xe_gt_throttle.c#L241

> 
> BR,
> Jani.
> 
>