[v3,32/50] qapi2texi: add 'If:' section to generated documentation

The documentation is generated only once, and doesn't know C
pre-conditions. Add 'If:' sections for top-level entities.

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 scripts/qapi2texi.py | 24 +++++++++++++-----------
 1 file changed, 13 insertions(+), 11 deletions(-)

Cc: Eric for an additional pair of eyeballs.

Marc-André Lureau <marcandre.lureau@redhat.com> writes:

> The documentation is generated only once, and doesn't know C
> pre-conditions. Add 'If:' sections for top-level entities.

Is this what we want?

QMP also exists only once.  Should the generated qemu-qmp-ref.* document
that instance of QMP, or should it document all potential instances of
QMP?

> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> ---
>  scripts/qapi2texi.py | 24 +++++++++++++-----------
>  1 file changed, 13 insertions(+), 11 deletions(-)
>
> diff --git a/scripts/qapi2texi.py b/scripts/qapi2texi.py
> index e72e7cfe0b..150e7045d2 100755
> --- a/scripts/qapi2texi.py
> +++ b/scripts/qapi2texi.py
> @@ -132,7 +132,6 @@ def texi_enum_value(value):
>      """Format a table of members item for an enumeration value"""
>      return '@item @code{%s}\n' % value.name
>  
> -
>  def texi_member(member, suffix=''):
>      """Format a table of members item for an object type member"""
>      typ = member.type.doc_type()

Spurious whitespace change.  PEP8 wants the original spacing here.

> @@ -175,7 +174,7 @@ def texi_members(doc, what, base, variants, member_func):
>      return '\n@b{%s:}\n@table @asis\n%s@end table\n' % (what, items)
>  
>  
> -def texi_sections(doc):
> +def texi_sections(doc, ifcond):
>      """Format additional sections following arguments"""
>      body = ''
>      for section in doc.sections:
> @@ -189,14 +188,16 @@ def texi_sections(doc):
>              body += '\n\n@b{%s:}\n' % name
>  
>          body += func(doc)
> +    if ifcond:
> +        body += '\n\n@b{If:} @code{%s}' % ifcond
>      return body
>  
>  
> -def texi_entity(doc, what, base=None, variants=None,
> +def texi_entity(doc, what, ifcond, base=None, variants=None,
>                  member_func=texi_member):
>      return (texi_body(doc)
>              + texi_members(doc, what, base, variants, member_func)
> -            + texi_sections(doc))
> +            + texi_sections(doc, ifcond))
>  
>  
>  class QAPISchemaGenDocVisitor(qapi.QAPISchemaVisitor):
> @@ -213,7 +214,7 @@ class QAPISchemaGenDocVisitor(qapi.QAPISchemaVisitor):
>              self.out += '\n'
>          self.out += TYPE_FMT(type='Enum',
>                               name=doc.symbol,
> -                             body=texi_entity(doc, 'Values',
> +                             body=texi_entity(doc, 'Values', ifcond,
>                                                member_func=texi_enum_value))
>  
>      def visit_object_type(self, name, info, ifcond, base, members, variants):
> @@ -224,7 +225,8 @@ class QAPISchemaGenDocVisitor(qapi.QAPISchemaVisitor):
>              self.out += '\n'
>          self.out += TYPE_FMT(type='Object',
>                               name=doc.symbol,
> -                             body=texi_entity(doc, 'Members', base, variants))
> +                             body=texi_entity(doc, 'Members', ifcond,
> +                                              base, variants))
>  
>      def visit_alternate_type(self, name, info, ifcond, variants):
>          doc = self.cur_doc
> @@ -232,7 +234,7 @@ class QAPISchemaGenDocVisitor(qapi.QAPISchemaVisitor):
>              self.out += '\n'
>          self.out += TYPE_FMT(type='Alternate',
>                               name=doc.symbol,
> -                             body=texi_entity(doc, 'Members'))
> +                             body=texi_entity(doc, 'Members', ifcond))
>  
>      def visit_command(self, name, info, ifcond, arg_type, ret_type,
>                        gen, success_response, boxed):
> @@ -242,9 +244,9 @@ class QAPISchemaGenDocVisitor(qapi.QAPISchemaVisitor):
>          if boxed:
>              body = texi_body(doc)
>              body += '\n@b{Arguments:} the members of @code{%s}' % arg_type.name
> -            body += texi_sections(doc)
> +            body += texi_sections(doc, ifcond)
>          else:
> -            body = texi_entity(doc, 'Arguments')
> +            body = texi_entity(doc, 'Arguments', ifcond)
>          self.out += MSG_FMT(type='Command',
>                              name=doc.symbol,
>                              body=body)
> @@ -255,7 +257,7 @@ class QAPISchemaGenDocVisitor(qapi.QAPISchemaVisitor):
>              self.out += '\n'
>          self.out += MSG_FMT(type='Event',
>                              name=doc.symbol,
> -                            body=texi_entity(doc, 'Arguments'))
> +                            body=texi_entity(doc, 'Arguments', ifcond))
>  
>      def symbol(self, doc, entity):
>          self.cur_doc = doc
> @@ -266,7 +268,7 @@ class QAPISchemaGenDocVisitor(qapi.QAPISchemaVisitor):
>          assert not doc.args
>          if self.out:
>              self.out += '\n'
> -        self.out += texi_body(doc) + texi_sections(doc)
> +        self.out += texi_body(doc) + texi_sections(doc, None)
>  
>  
>  def texi_schema(schema):

Missing: coverage in tests/qapi-schema/doc-good.json.

On 12/13/2017 06:35 AM, Markus Armbruster wrote:
> Cc: Eric for an additional pair of eyeballs.
> 
> Marc-André Lureau <marcandre.lureau@redhat.com> writes:
> 
>> The documentation is generated only once, and doesn't know C
>> pre-conditions. Add 'If:' sections for top-level entities.
> 
> Is this what we want?
> 
> QMP also exists only once.  Should the generated qemu-qmp-ref.* document
> that instance of QMP, or should it document all potential instances of
> QMP?
> 

I can go either way; it's nice to know that the binary that this copy of
documentation was bundled with only understands these terms (the binary
was compiled without HAVE_FOO, so any code guarded by HAVE_FOO doesn't
need to be documented); but that limits the usability of that
documentation to just that binary.  It's also useful to have
fully-generic documentation hosted on the website, where everything is
documented (the documentation describes all possible builds of qemu
2.12, not just the one you installed), while mentioning the conditional
nature of the documented feature ("qemu in general knows about these
things; but check your particular binary by doing XYZ to learn if that
support was compiled in to your binary").

So having typed that, I think I'm leaning slightly towards documenting
everything, including conditionals, rather than trimming the document to
match the current build conditions.