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

[Rodrigo Vivi <rodrigo.vivi@intel.com>]

On Tue, Sep 30, 2025 at 07:46:29PM +0200, Michal Wajdeczko wrote:
> 
> 
> 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

I'd like to get the view of Lucas and Thomas here as well, but I'm with
Michal here. I prefer to request all the public functions to have the
kernel doc style. So we ensure that we don't miss documentation, we
follow a standard and author gets to consideration of the params and
all, like Michal described.

Having that as part of sphynx doc build or not is a different discussion
as it needs to be included in the Documentation/gpu/*.rst

> 
>