[LTP] [PATCH v3 1/2] doc: Document process_state

[Petr Vorel]

Hi Cyril, Andrea,

more fixes needed:

> +++ b/include/tst_process_state.h
...
>   */
>  #define TST_PROCESS_STATE_WAIT(pid, state, msec_timeout) \
>  	tst_process_state_wait(__FILE__, __LINE__, NULL, \
>  			(pid), (state), (msec_timeout))

> -/*
> - * Check that a given pid is present on the system
> +/**
> + * TST_PROCESS_EXIT_WAIT() - Waits while pid is present on the system.
> + *
> + * Loops until `kill($PID, 0)` succeds or timeout is reached.
> + *
> + * @pid A process pid.
          ^ missing ':' here leads to "pid – undescribed" in generated doc,
see ./doc/html/developers/api_c_tests.html#macro-tst-process-exit-wait

@Andrea: I wish sphinx doc would warn about "undescribed" and I thought it did
in the past, but I don't see it.

Also we have too many (~ 220x) warnings:
"WARNING: duplicate label description, other instance in ..." it's not usable.
Any hint you could have look on it? If we solve this warning would get useful.

> + * @msec_timeout: A timeout for the wait.
>   */
>  #define TST_PROCESS_EXIT_WAIT(pid, msec_timeout) \
>  	tst_process_exit_wait((pid), (msec_timeout))

> -/*
> - * Waits for thread state change.
> +/**
> + * TST_THREAD_STATE_WAIT() - Waits for a thread state change.
>   *
> - * The state is one of the following:
> + * Polls `/proc/self/task/$TID/state` for a thread state change.
>   *
> - * R - running
> - * S - sleeping
> - * D - disk sleep
> - * T - stopped
> - * t - tracing stopped
> - * Z - zombie
> - * X - dead
> + * Possible thread states are the same as for TST_PROCESS_STATE_WAIT().

And here we have "undescribed" due not being described:

Parameters:
tid – undescribed
state – undescribed
msec_timeout – undescribed

See ./doc/html/developers/api_c_tests.html#macro-tst-thread-state-wait

Kind regards,
Petr

>   */
>  #define TST_THREAD_STATE_WAIT(tid, state, msec_timeout) \
>  	tst_thread_state_wait((tid), (state), (msec_timeout))