Re: [PATCH] docs: Format (void *) to fix reStructuredText emphasis warnings

[Nicola Vetrini <nicola.vetrini@xxxxxxxxxxx>]

On 2026-04-28 20:34, Bernhard Kaindl wrote:
> Fix warnings when rendering the Sphinx documentation because
> with reStructuredText, in the character sequence of '(void *)',
> the characters *) are seen as an emphasis start-string:
>
> WARNING: Inline emphasis start-string without end-string. [docutils]
>
> Fix this by formatting it with ``(void *)`` as an inline literal
> which can be used for monospaced code snippets like these that
> can contain any characters without any markup interpretation.
>
> Signed-off-by: Bernhard Kaindl <bernhard.kaindl@xxxxxxxxxx>
Reviewed-by: Nicola Vetrini <nicola.vetrini@xxxxxxxxxxx>

See nit below
> ---
> Preview based on the new theme and design docs arrangement just 
> submitted:
> https://bernhard-xen.readthedocs.io/en/void/misra/rules.html
> https://bernhard-xen.readthedocs.io/en/void/misra/deviations.html
> ---
>  docs/misra/deviations.rst | 4 ++--
>  docs/misra/rules.rst      | 6 +++---
>  2 files changed, 5 insertions(+), 5 deletions(-)
>
> diff --git a/docs/misra/deviations.rst b/docs/misra/deviations.rst
> index b04830959694..c972d5b2ad49 100644
> --- a/docs/misra/deviations.rst
> +++ b/docs/misra/deviations.rst
> @@ -366,13 +366,13 @@ Deviations related to MISRA C:2012 Rules:
>       - Tagged as `safe` for ECLAIR.
>
>     * - R11.1
> -     - The conversion from a function pointer to unsigned long or 
> '(void *)' does
> +     - The conversion from a function pointer to unsigned long or 
> ``(void *)`` does
>         not lose any information, provided that the target type has 
> enough bits
>         to store it.
>       - Tagged as `safe` for ECLAIR.
>
>     * - R11.1
> -     - Conversion from unsigned long or '(void *)' to a function 
> pointer can
> +     - Conversion from unsigned long or ``(void *)`` to a function 
> pointer can
>         restore full information, provided that the source type has 
> enough bits
>         to restore it.
There are further instance below which should similarly be rendered with 
a monospaced font, as they are code
e.g.

The conversion from ‘void noreturn (*)(…)’ to ‘void (*)(…)’ is safe 
because the semantics of the ‘noreturn’ attribute
Perhaps those don't cause warnings, but if we want to visualize this as 
code in a monospaced font, then it probably should be uniformly used in 
the document. We haven't been 100% consistent when writing these 
documents originally; partly due to the fact that different people were 
involved, but this could be an occasion to remedy that.
But perhaps that is best done in a follow-up patch, so feel free to take 
my r-by for this patch.
>       - Tagged as `safe` for ECLAIR.
> diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
> index b3e929307d51..fc6fdfd313d0 100644
> --- a/docs/misra/rules.rst
> +++ b/docs/misra/rules.rst
> @@ -430,9 +430,9 @@ maintainers if you want to suggest a change.
>         and any other type
>       - All conversions to integer types are permitted if the 
> destination
>         type has enough bits to hold the entire value. Conversions to 
> bool
> -       and void* are permitted. Conversions from 'void noreturn 
> (*)(...)'
> -       to 'void (*)(...)' are permitted. Conversions from unsigned 
> long or
> -       '(void *)' to a function pointer are permitted.
> +       and ``void *`` are permitted. Conversions from ``void noreturn 
> (*)(...)``
> +       to ``void (*)(...)`` are permitted. Conversions from unsigned 
> long or
> +       ``(void *)`` to a function pointer are permitted.
>         Example::
>
>             unsigned long func_addr = (unsigned long)&some_function;
--
Nicola Vetrini, B.Sc.
Software Engineer
BUGSENG (https://bugseng.com)
LinkedIn: https://www.linkedin.com/in/nicola-vetrini-a42471253