Re: [LTP] [PATCH v3 2/2] include: doc: Convert comments into linuxdoc

Petr Vorel
2024-04-04T13:42:45Z

> Hi!
> > Very nit: I would prefer if the formatting would not force the indent, e.g.:

> > * @tcnt: A number of tests. If set the test() callback is called tcnt times
> > * and each time passed an increasing counter value.

> > Because variables with long name will require more lines, but feel free to
> > ignore it.

> I do not have a strong opinion here, but I guess that we should add at
> least a single space before the subsequent lines so that it's clear that
> it's a continuation.

That's IMHO better, but feel free to ignore (it's not important).

> Does anyone else have an opinion on this?

> > > + * @options: An NULL optstr terminated array of struct tst_option.
> > > + *
> > > + * @min_kver: A minimal kernel version the test can run on. e.g. "3.10".
> > > + *
> > > + * @supported_archs: A NULL terminated array of architectures the test runs on
> > > + * e.g. {"x86_64, "x86", NULL}. Calls tst_is_on_arch() to
> > > + * check if current CPU architecture is supported and exits
> > > + * the test with TCONF if it's not.
> > > + *

> > ...
> > > void (*setup)(void);
> > > void (*cleanup)(void);
> > > -
> > > void (*test)(unsigned int test_nr);
> > > void (*test_all)(void);

> > > - /* Syscall name used by the timer measurement library */
> > We decided to drop this comment. Isn't it useful?
> > > const char *scall;
> > > -
> > > - /* Sampling function for timer measurement testcases */
> > > int (*sample)(int clk_id, long long usec);
> > And this one as well.

> The sampling is a kind of hack, I would like to rethink it a bit if it
> can't be done in a cleaner way before documenting it.

Sure, ack.

Kind regards,
Petr