Markus Armbruster <arm...@redhat.com> wrote: > Signed-off-by: Markus Armbruster <arm...@redhat.com>
Reviewed-by: Juan Quintela <quint...@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.
