[LTP] [PATCH v2 4/9] include: Document assertion API macros

[Petr Vorel]

Hi Andrea,

..
> +/**
> + * TST_ASSERT_FILE_STR() - Asserts that string value for field in file equals val.
> + *
> + * @path: Path to the file to check.
> + * @prefix: Field name or prefix preceding the string value.
> + * @val: Expected string value.
> + *
> + * Scans lines in path for prefix followed by ": " and a string value.
nit: there might be more whitespace chars after ":". Also formatting by `` ``
might be better.

* Scans lines in path for prefix followed by ``:`` followed by whitespace and a string value.

Otherwise LGTM.
Reviewed-by: Petr Vorel <pvorel@suse.cz>

> + * Reports :c:enum:`TPASS <tst_res_flags>` on match, or
> + * :c:enum:`TFAIL <tst_res_flags>` on mismatch.
> + */
>  #define TST_ASSERT_FILE_STR(path, prefix, val) \
>  	tst_assert_file_str(__FILE__, __LINE__, path, prefix, val)

> -/*
> - * Asserts that a string value stored in the prefix field of file pointed by path
> - * equals to the value passed to this function. This is mostly useful for
> - * asserting correct field values in sysfs, procfs, etc.
> - */
>  void tst_assert_file_str(const char *file, const int lineno,
>  			 const char *path, const char *prefix, const char *val);

I guess it's safe to expect the readers will be using macros, not the functions
themselves (that's for use in LTP library itself) => good to move kerneldoc from
functions to macros.

Kind regards,
Petr