[PATCH 1/2] eng: Document test framework formatted output

[Gedare Bloom]

On Sun, Feb 9, 2020 at 3:20 AM Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
>
> Update #3199.
> ---
>  eng/test-framework.rst | 30 +++++++++++++++++++++++-------
>  1 file changed, 23 insertions(+), 7 deletions(-)
>
> diff --git a/eng/test-framework.rst b/eng/test-framework.rst
> index 50745df..6380f7e 100644
> --- a/eng/test-framework.rst
> +++ b/eng/test-framework.rst
> @@ -982,10 +982,10 @@ fails.
>      P:0:0:UI1:test-psx.c:13
>      E:stat:N:1:F:0
>
> -Custom Log Messages
> --------------------
> +Log Messages and Formatted Output
> +---------------------------------
>
> -You can print custom log messages with the `T_log()` function:
> +You can print log messages with the `T_log()` function:
>
>  .. code-block:: c
>
> @@ -994,24 +994,40 @@ You can print custom log messages with the `T_log()` function:
>  A newline is automatically added to terminate the log message line.
>
>  .. code-block:: c
> -    :caption: Custom Log Message Example
> +    :caption: Log Message Example
>
>      #include <t.h>
>
>      T_TEST_CASE(log)
>      {
> -        T_log(T_NORMAL, "a custom message %i, %i, %i", 1, 2, 3);
> +        T_log(T_NORMAL, "a log message %i, %i, %i", 1, 2, 3);
>          T_set_verbosity(T_QUIET);
>          T_log(T_NORMAL, "not verbose enough");
>      }
>
>  .. code-block:: none
> -    :caption: Custom Log Message Report
> +    :caption: Log Message Report
>
>      B:log
> -    L:a custom message 1, 2, 3
> +    L:a log message 1, 2, 3
>      E:log:N:0:F:0
>
> +You can use the following functions to print formatted output:
> +
> +.. code-block:: c
> +
> +    int T_printf(char const *, ...);
> +
> +    int T_vprintf(char const *, va_list);
> +
> +    int T_snprintf(char *, size_t, const char *, ...);
> +
> +In contrast to the corresponding standard C library functions, floating-point
> +and exotic formats may be not supported.  On some architectures supported by

Minor English grammar: "may not be" is the correct way to express the
possibility something is not.

"may be not" is used infrequently and implies certainty something is
not, usually combined with a contrasting statement, e.g., "Exotic
formats may be not supported, but primitive C types will work." Again,
this is a rare grammatical form; one would usually say "are not" in
these cases.


> +RTEMS, floating-point operations are only supported in special tasks and may be
> +forbidden in interrupt context.  These formatted output functions work in every
> +context.
> +
>  Time Services
>  -------------
>
> --
> 2.16.4
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel