| Message ID | 20230427095346.1238913-1-armbru@redhat.com |
|---|---|
| State | New |
| Headers | show |
| Series | None | expand |
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.
Juan Quintela <quintela@redhat.com> writes: > Markus Armbruster <armbru@redhat.com> wrote: >> Signed-off-by: Markus Armbruster <armbru@redhat.com> > > Reviewed-by: Juan Quintela <quintela@redhat.com> Thanks! >> --- >> 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 [...] >> +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 Make sure building documentation is enabled, run "make", and look at bld-clang/docs/manual/interop/qemu-qmp-ref.html. Documentation for qapi/migration.json is in section "Migration" (because qapi/migration.json starts with a "# = Migration" heading). Sphinx can produce a number of formats. Our build system only does HTML and manual pages. I like to also produce plain text for easy diffing. I grab the sphinx-build invocation from "make V=1" and replace "-b html" by "-b text".
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 > + > +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 > ================================== >
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 >> ================================== >
Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru> writes: > 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 Patches I'm about to post will fill up this pitfall. They change the text to: # @none: None (no memory side cache in this proximity domain, # or cache associativity unknown) # (since 5.0) The last line's de-indent is wrong. The second and subsequent lines need to line up with each other, like this:: # @none: None (no memory side cache in this proximity domain, # or cache associativity unknown) # (since 5.0) Good enough? [...]
On 28.04.23 12:34, Markus Armbruster wrote: > Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru> writes: > >> 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 > > Patches I'm about to post will fill up this pitfall. They change the > text to: > > # @none: None (no memory side cache in this proximity domain, > # or cache associativity unknown) > # (since 5.0) > > The last line's de-indent is wrong. The second and subsequent lines So you want to drop "The description is parsed as a definition list ..." ? > need to line up with each other, like this:: > > # @none: None (no memory side cache in this proximity domain, > # or cache associativity unknown) > # (since 5.0) > > Good enough? Example of good indent is good)
Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru> writes: > On 28.04.23 12:34, Markus Armbruster wrote: >> Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru> writes: >> >>> 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 >> >> Patches I'm about to post will fill up this pitfall. They change the >> text to: >> >> # @none: None (no memory side cache in this proximity domain, >> # or cache associativity unknown) >> # (since 5.0) >> The last line's de-indent is wrong. The second and subsequent lines > > So you want to drop "The description is parsed as a definition list ..." ? Yes, because that'll be factually wrong :) Happy to explain further once the patches are on the list. >> need to line up with each other, like this:: >> >> # @none: None (no memory side cache in this proximity domain, >> # or cache associativity unknown) >> # (since 5.0) >> >> Good enough? > > Example of good indent is good) Thanks!
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! + + Client JSON Protocol introspection ==================================
Signed-off-by: Markus Armbruster <armbru@redhat.com> --- docs/devel/qapi-code-gen.rst | 53 ++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+)