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

Cyril Hrubis
2024-04-04T12:56:40Z

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.

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.

--
Cyril Hrubis
chrubis@suse.cz