[LTP] [PATCH 2/2] doc: Convert more C API info

[Andrea Cervesato]

Hi!

On 5/16/24 13:20, Petr Vorel wrote:
> Convert more C API info (both library and user).
>
> These info were omitted when converted from GitHub asciidoc wiki format.
>
> Fixes: 4a72aada8 ("New LTP documentation")
> Signed-off-by: Petr Vorel <pvorel@suse.cz>
> ---
>   doc/developers/api_c_tests.rst |  7 +++++
>   doc/developers/ltp_library.rst | 47 ++++++++++++++++++++++++++++++++--
>   2 files changed, 52 insertions(+), 2 deletions(-)
>
> diff --git a/doc/developers/api_c_tests.rst b/doc/developers/api_c_tests.rst
> index ec53ab33c..c7e1a5997 100644
> --- a/doc/developers/api_c_tests.rst
> +++ b/doc/developers/api_c_tests.rst
> @@ -12,6 +12,13 @@ Core LTP API
>   .. kernel-doc:: ../../include/tst_res_flags.h
>   .. kernel-doc:: ../../include/tst_test.h
>   
> +LAPI headers
> +------------
> +
> +Use our LAPI headers (``include "lapi/foo.h"``) to keep compatibility with old
> +distributions. LAPI header should always include original header. For more info
> +see :doc:`../developers/ltp_library`.
> +
>   Option parsing
>   --------------
>   
> diff --git a/doc/developers/ltp_library.rst b/doc/developers/ltp_library.rst
> index 723781feb..15dde8e7b 100644
> --- a/doc/developers/ltp_library.rst
> +++ b/doc/developers/ltp_library.rst
> @@ -9,8 +9,51 @@ General Rules
>   When we extend library API, we need to apply the same general rules that we use
>   when writing tests, plus:
>   
> -#. LTP library tests must go inside :master:`lib/newlib_tests` directory
> -#. LTP documentation has to be updated according to API changes
> +#. LTP library tests must go inside :master:`lib/newlib_tests` directory.
> +#. LTP documentation has to be updated according to API changes.
> +#. Environment variables should be listed in :doc:`../users/setup_tests`.
> +
> +C API
> +-----
> +
> +LAPI headers
> +~~~~~~~~~~~~
> +
> +Use our LAPI headers (``include "lapi/foo.h"``) to keep compatibility with old
> +distributions. LAPI header should always include original header. Older linux
> +headers were problematic, therefore we preferred to use libc headers. There are
> +still some bugs when combining certain glibc headers with linux headers, see
> +https://sourceware.org/glibc/wiki/Synchronizing_Headers.
> +

I generally prefer to have a single point where features are documented, 
otherwise we need to remember
to update documentation in two parts instead of one.

> +Rules checked with ``make check``
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +LTP-001: Sources have ``tst_`` prefix
> +"""""""""""""""""""""""""""""""""""""
> +
> +API source code is in headers in ``include/{empty}*.h``,
> +``include/lapi/{empty}*.h`` (backward compatibility for old kernel and libc)
> +and C sources in ``lib/{empty}*.c``. Files have ``tst_`` prefix.
> +
> +LTP-002: TST_RET and TST_ERR are not modified
> +"""""""""""""""""""""""""""""""""""""""""""""
> +
> +The test author is guaranteed that the test API will not modify these
> +variables. This prevents silent errors where the return value and
> +errno are overwritten before the test has chance to check them.
> +
> +The macros which are clearly intended to update these variables. That
> +is ``TEST`` and those in 'tst_test_macros.h'. Are of course allowed to
> +update these variables.
> +
> +LTP-003: Externally visible library symbols have the ``tst_`` prefix
> +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
> +
> +Functions, types and variables in the public test API should have the
> +``tst_`` prefix. With some exceptions for symbols already prefixed with
> +``safe_`` or ``ltp_``.
> +
> +Static (private) symbols should not have the prefix.
>   
>   Shell API
>   ---------

Andrea