Re: [PATCH] Improved reStructuredText formatting of Misra C Rules

[Jan Beulich <jbeulich@xxxxxxxx>]

On 29.04.2026 09:22, Bernhard Kaindl wrote:
> Code blocks in the RFC rules can be converted as C syntax-highlighted
> pretty pieces of code using `.. code:: C` inline elements:
> https://docutils.sourceforge.io/docs/ref/rst/directives.html#code
> 
> For reference, the current formatting used are 'Indented Literal Blocks':
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#toc-entry-23
> 
> In this example, docs/misra/rules.rst, line 128 starts an Indented
> Literal Block by ending the paragraph with "violations::"
> (note the :: at then end of the paragraph which is enables it):
> 
>          - Functions that are no-return due to calls to the 
> `ASSERT_UNREACHABLE()`
>            macro in debug build configurations are not considered violations::
> 
>               static inline bool
>               arch_vcpu_ioreq_completion(enum vio_completion completion)
>               {
>                   ASSERT_UNREACHABLE();
>                   return false;
>               }
> 
> Format such code blocks as C code blocks and apply ``function()`` around
> functions to make them inline linterals for monospace formatting.

Nit: literal

> --- a/docs/misra/rules.rst
> +++ b/docs/misra/rules.rst
> @@ -115,20 +115,29 @@ maintainers if you want to suggest a change.
>       - Required
>       - A project shall not contain unreachable code
>       - The following are allowed:
> -         - Invariantly constant conditions, e.g. if(IS_ENABLED(CONFIG_HVM)) 
> { S; }
> +         - Invariantly constant conditions, e.g.
> +
> +           .. code:: C
> +
> +              if ( IS_ENABLED(CONFIG_HVM) ) {
> +                S;
> +              }

If already you reformat like this, then please fully to proper Xen style.

>           - Switch with a controlling value statically determined not to
>             match one or more case statements
>           - Functions that are intended to be referenced only from
> -           assembly code (e.g. 'do_trap_fiq')
> -         - asm-offsets.c, as they are not linked deliberately, because
> +           assembly code (e.g. ``do_trap_fiq``)
> +         - ``asm-offsets.c``, as they are not linked deliberately, because

This is a file name, not code?

>             they are used to generate definitions for asm modules
>           - Declarations without initializer are safe, as they are not
>             executed
> -         - Functions that are no-return due to calls to the 
> `ASSERT_UNREACHABLE()`
> -           macro in debug build configurations are not considered 
> violations::
> +         - Functions that are no-return due to calls to the 
> ``ASSERT_UNREACHABLE()``
> +           macro in debug build configurations are not considered violations:
> +
> +           .. code:: C
>  
>                static inline bool
> -              arch_vcpu_ioreq_completion(enum vio_completion completion)
> +              arch_vcpu_ioreq_completion(int c)

I don't agree with making a change making an example not match actual code.
If you truly want to abstract this (to shorten the line) then please also
change the function name.

> @@ -207,16 +216,20 @@ maintainers if you want to suggest a change.
>  
>         Clashes between bitops functions and macro names are allowed
>         because they are used for input validation and error handling.
> -       Example::
> +       Example:
>  
> -           static inline void set_bit(int nr, volatile void *addr)
> +       .. code:: C
> +
> +           static inline void set_bit(int nr, volatile void *a)
>             {
> -               asm volatile ( "lock btsl %1,%0"
> -                              : "+m" (ADDR) : "Ir" (nr) : "memory");
> +               asm volatile ( "lock btsl %1,%0 "

Why the new trailing blank in the string literal?

> +                              : "+m" (a)
> +                              : "Ir" (nr) : "memory");

Where you want to add a blank while re-flowing is before the parenthesis
here.

>             }
> -           #define set_bit(nr, addr) ({                            \
> -               if ( bitop_bad_size(addr) ) __bitop_bad_size();     \
> -               set_bit(nr, addr);                                  \
> +
> +           #define set_bit(nr, addr) ({                       \
> +               if ( bitop_bad_size(addr) ) __bitop_bad_size();\

There wants to be a blank before the semicolon. To better shorten line
length:

               if ( bitop_bad_size(addr) ) \
                   __bitop_bad_size();     \

Jan