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

[Vladimir Sementsov-Ogievskiy]

On 27.04.23 15:41, Vladimir Sementsov-Ogievskiy wrote:
> On 27.04.23 12:53, Markus Armbruster wrote:
> > Signed-off-by: Markus Armbruster <armbru@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)".
>
> May be add good example of indentation as well

anyway:
Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>

> > +
> > +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!
> > +
> > +
> >   Client JSON Protocol introspection
> >   ==================================

--
Best regards,
Vladimir