RE: [PATCH i-g-t 1/7] tests/intel/kms_mst_helper: Add kernel-doc for existing function

Kandpal, Suraj
2026-04-13T05:14:04Z

> > > Convert the doc comment on igt_find_all_mst_output_in_topology
> > > to proper kernel-doc.
>
> Maybe wrote 'proper IGT doc.'
>
> Add also a note about a typo fix.
>
> > >
> > > Signed-off-by: Kunal Joshi <kunal1.joshi@intel.com>
> > > ---
> > > tests/intel/kms_mst_helper.c | 5 +++--
> > > 1 file changed, 3 insertions(+), 2 deletions(-)
> > >
> > > diff --git a/tests/intel/kms_mst_helper.c
> > > b/tests/intel/kms_mst_helper.c index aef74cd31..38859cffc 100644
> > > --- a/tests/intel/kms_mst_helper.c
> > > +++ b/tests/intel/kms_mst_helper.c
> > > @@ -5,11 +5,12 @@
> > >
> > > #include "kms_mst_helper.h"
> > >
> > > -/*
> > > +/**
> > > + * igt_find_all_mst_output_in_topology:
> > > * @drm_fd: DRM file descriptor
> > > * @display: pointer to #igt_display_t structure
> > > * @output: target output
> > > - * @mst_outputs: filled with mst output of same toplogy as @output
> > > + * @mst_outputs: filled with mst output of same topology as @output
> > > * @num_mst_outputs: filled with count of mst outputs found in topology
> > > *
> > > * Iterates over all connected outputs and adds each DP MST
> >
> > Can we have the following way of documenting functions? This is what
> > we do in kernel
> > igt_find_all_mst_output_in_topology() - Find all MST outputs
>
> I do not know if that is possible without breaking already exiting IGT
> documentation.
> +cc few more KMS devs and Pawel
>
> Cc: Juha-Pekka Heikkila <juhapekka.heikkila@gmail.com>
> Cc: Juha-Pekka Heikkila <juha-pekka.heikkila@intel.com>
> Cc: Karthik B S <karthik.b.s@intel.com>
> Cc: Pawel Sikora <pawel.sikora@intel.com>
> Cc: Swati Sharma <swati2.sharma@intel.com>
>
> > arguments like you have done above
> > Description of function like you have already done
> >
> > Rest Looks good
> >
> > Regards,
> > Suraj Kandpal
> >
>
> Format here is what we currently use in other IGT parts, see for example
> lib/igt_alsa.c so with commit description fixed

I have no problem with the format but a lot of places have described comments for the very differently
For example
In lib/igt_core.c
In the same file we have functions not following the same documentation formats which already breaks documentation
Check : igt_system_quiet, igt_measured_usleep
Or even kms_mst_helper.c itself in which both the current functions defined don't follow the documentation in igt_alsa.c

There are too many places that end up breaking this format.
Someone needs to fix a lot of these places.
Otherwise reviewers wont know which is the correct one and wont be able to add a comment regarding this letting more wrong documentation sneak in into the code.
Also if the one writing the code refers to the wrong documentation they will continue this cycle.

Regards,
Suraj Kandpal

>
> Reviewed-by: Kamil Konieczny <kamil.konieczny@linux.intel.com>
>
> Regards,
> Kamil
>
> > > --
> > > 2.25.1
> >