Re: [PATCH 17/16] docs/devel/qapi-code-gen: Describe some doc markup pitfalls

[Juan Quintela]

Markus Armbruster <armbru@redhat.com> wrote:
> Signed-off-by: Markus Armbruster <armbru@redhat.com>

Reviewed-by: Juan Quintela <quintela@redhat.com>

> ---
>  docs/devel/qapi-code-gen.rst | 53 ++++++++++++++++++++++++++++++++++++
>  1 file changed, 53 insertions(+)
>
> diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
> index d81aac7a19..14983b074c 100644
> --- a/docs/devel/qapi-code-gen.rst
> +++ b/docs/devel/qapi-code-gen.rst
> @@ -1059,6 +1059,59 @@ For example::
>     'returns': ['BlockStats'] }
>  
>  
> +Markup pitfalls
> +~~~~~~~~~~~~~~~
> +
> +A blank line is required between list items and paragraphs.  Without
> +it, the list may not be recognized, resulting in garbled output.  Good
> +example::
> +
> + # An event's state is modified if:
> + #
> + # - its name matches the @name pattern, and
> + # - if @vcpu is given, the event has the "vcpu" property.
> +
> +Without the blank line this would be a single paragraph.
> +
> +Indentation matters.  Bad example::
> +
> + # @none: None (no memory side cache in this proximity domain,
> + #              or cache associativity unknown)
> +
> +The description is parsed as a definition list with term "None (no
> +memory side cache in this proximity domain," and definition "or cache
> +associativity unknown)".
> +
> +Section tags are case-sensitive and end with a colon.  Good example::
> +
> + # Since: 7.1
> +
> +Bad examples (all ordinary paragraphs)::
> +
> + # since: 7.1
> +
> + # Since 7.1
> +
> + # Since : 7.1
> +
> +Likewise, member descriptions require a colon.  Good example::
> +
> + # @interface-id: Interface ID
> +
> +Bad examples (all ordinary paragraphs)::
> +
> + # @interface-id   Interface ID
> +
> + # @interface-id : Interface ID
> +
> +Undocumented members are not flagged, yet.  Instead, the generated
> +documentation describes them as "Not documented".  Think twice before
> +adding more undocumented members.
> +
> +When you change documentation comments, please check the generated
> +documentation comes out as intended!

What is the easiest way to see the code generated for some subsystem,
say migration.json and find the problems and undocumented stuff?

I am expecting something in the lines of:
- you run this command
- and look at this file

Thanks, Juan.