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

[Petr Vorel]

Hi Cyril,

> Signed-off-by: Cyril Hrubis <chrubis@suse.cz>
> Reviewed-by: Petr Vorel <pvorel@suse.cz>
> ---
>  doc/conf.py                    |  1 +
>  doc/developers/api_c_tests.rst |  5 ++++
>  include/tst_process_state.h    | 47 +++++++++++++++++++---------------
>  3 files changed, 33 insertions(+), 20 deletions(-)

> diff --git a/doc/conf.py b/doc/conf.py
> index b8ec1c31c..5d7362439 100644
> --- a/doc/conf.py
> +++ b/doc/conf.py
> @@ -36,6 +36,7 @@ extlinks = {
>      'master': (f'{ltp_repo}/blob/master/%s', '%s'),
>      'shell_lib': (f'{ltp_repo}/blob/master/testcases/lib/%s', '%s'),
>      'git_man': ('https://git-scm.com/docs/git-%s', 'git %s'),
> +    'man1': ('https://man7.org/linux/man-pages/man1/%s.1.html', '%s(1)'),

I'm sorry, due today's improvement
https://github.com/linux-test-project/ltp/commit/de27451e837a6d17c8ebf1a55b5ade87223882f4
could you please drop doc/conf.py change because :man1: is not needed any more.

>      'man2': ('https://man7.org/linux/man-pages/man2/%s.2.html', '%s(2)'),
>      'man3': ('https://man7.org/linux/man-pages/man3/%s.3.html', '%s(3)'),
>      # TODO: allow 2nd parameter to show page description instead of plain URL
> diff --git a/doc/developers/api_c_tests.rst b/doc/developers/api_c_tests.rst
> index 2ca0f0464..13fc8651b 100644
> --- a/doc/developers/api_c_tests.rst
> +++ b/doc/developers/api_c_tests.rst
> @@ -43,6 +43,11 @@ Kernel
>  .. kernel-doc:: ../../include/tst_kernel.h
>  .. kernel-doc:: ../../include/tst_kvercmp.h

> +Process state
> +-------------
> +
> +.. kernel-doc:: ../../include/tst_process_state.h
> +
>  NUMA
>  ----
>  .. kernel-doc:: ../../include/tst_numa.h
> diff --git a/include/tst_process_state.h b/include/tst_process_state.h
> index b1d83e109..fd94ee207 100644
> --- a/include/tst_process_state.h
> +++ b/include/tst_process_state.h
> @@ -15,39 +15,46 @@

>  #ifdef TST_TEST_H__

> -/*
> - * Waits for process state change.
> +/**
> + * TST_PROCESS_STATE_WAIT() - Waits for a process state change.
> + *
> + * Polls `/proc/$PID/state` for a process state changes.
>   *
> - * The state is one of the following:
> + * @pid: A process pid.
> + * @state: A state to wait for.
> + * @msec_timeout: A timeout for the wait.
>   *
> - * R - process is running
> - * S - process is sleeping
> - * D - process sleeping uninterruptibly
> - * Z - zombie process
> - * T - process is traced
> + * Possible process states (see :man1:`ps`):

And this should be now :manpage:`ps(1)`.

Thank you!

Kind regards,
Petr