[LTP] [PATCH] doc: Add basic shell test description

[Petr Vorel]

> Signed-off-by: Cyril Hrubis <chrubis@suse.cz>
> ---
>  doc/developers/api_shell_tests.rst | 91 ++++++++++++++++++++++++++++++
>  1 file changed, 91 insertions(+)

> diff --git a/doc/developers/api_shell_tests.rst b/doc/developers/api_shell_tests.rst
> index b6e8560d9..bad9f1f4b 100644
> --- a/doc/developers/api_shell_tests.rst
> +++ b/doc/developers/api_shell_tests.rst
> @@ -2,3 +2,94 @@

>  LTP shell API
>  =============
> +
> +Shell API overview
> +------------------
> +
> +First lines of the shell test should be a shebang, a license, and copyrights.
> +
> +.. code-block:: shell
> +
> +   #!/bin/sh
> +   # SPDX-License-Identifier: GPL-2.0-or-later
> +   # Copyright 2099 Foo Bar <foo.bar@email.com>
very nit: maybe foo.bar@example.org?

...
> +At this point everything has been set up and we can finally write the test
> +function. The test results are reported by the usual functions `tst_res` and
> +`tst_brk`. As in the C API these functions store results into a piece of shared
> +memory as soon as they return so there is no need to propagate results event
> +from child processes.
> +
> +.. code-block:: shell
> +
> +   tst_test()
> +   {
> +        tst_res TPASS "Bar enabled Foo"
> +   }
> +
> +In order for the test to be actually executed the very last line of the script
> +must source the `tst_run.sh` script.

Also this could be :master:`testcases/lib/tst_run.sh`.

Of course, all the changes can be done before merging (no need to post v2).

Kind regards,
Petr