Re: [Qemu-devel] [PATCH for-2.9 25/47] qapi2texi: Include member type in generated documentation

[Marc-André Lureau]

Hi

On Mon, Mar 13, 2017 at 10:31 AM Markus Armbruster <address@hidden>
wrote:

> The recent merge of docs/qmp-commands.txt and docs/qmp-events.txt into
> the schema lost type information.  Fix this documentation regression.
>
> Example change (qemu-qmp-ref.txt):
>
>   -- Struct: InputKeyEvent
>
>       Keyboard input event.
>
>       Members:
> -     'button'
> +     'button: InputButton'
>            Which button this event is for.
> -     'down'
> +     'down: boolean'
>            True for key-down and false for key-up events.
>
>       Since: 2.0
>
> Signed-off-by: Markus Armbruster <address@hidden>
> ---
>  scripts/qapi.py      | 14 ++++++++++++++
>  scripts/qapi2texi.py |  8 ++++++--
>  2 files changed, 20 insertions(+), 2 deletions(-)
>
> diff --git a/scripts/qapi.py b/scripts/qapi.py
> index 9430493..b82a2a6 100644
> --- a/scripts/qapi.py
> +++ b/scripts/qapi.py
> @@ -1101,6 +1101,11 @@ class QAPISchemaType(QAPISchemaEntity):
>          }
>          return json2qtype.get(self.json_type())
>
> +    def doc_type(self):
> +        if self.is_implicit():
> +            return None
> +        return self.name
> +
>
>  class QAPISchemaBuiltinType(QAPISchemaType):
>      def __init__(self, name, json_type, c_type):
> @@ -1125,6 +1130,9 @@ class QAPISchemaBuiltinType(QAPISchemaType):
>      def json_type(self):
>          return self._json_type_name
>
> +    def doc_type(self):
> +        return self.json_type()
> +
>      def visit(self, visitor):
>          visitor.visit_builtin_type(self.name, self.info,
> self.json_type())
>
> @@ -1184,6 +1192,12 @@ class QAPISchemaArrayType(QAPISchemaType):
>      def json_type(self):
>          return 'array'
>
> +    def doc_type(self):
> +        elt_doc_type = self.element_type.doc_type()
> +        if not elt_doc_type:
> +            return None
>

In which case is this expected to happen? place an assert here instead?


Reviewed-by: Marc-André Lureau <address@hidden>




> +        return 'array of ' + elt_doc_type
> +
>      def visit(self, visitor):
>          visitor.visit_array_type(self.name, self.info, self.element_type)
>
> diff --git a/scripts/qapi2texi.py b/scripts/qapi2texi.py
> index 3dd0146..993b652 100755
> --- a/scripts/qapi2texi.py
> +++ b/scripts/qapi2texi.py
> @@ -135,8 +135,12 @@ def texi_enum_value(value):
>
>  def texi_member(member):
>      """Format a table of members item for an object type member"""
> -    return '@item @code{%s}%s\n' % (
> -        member.name, ' (optional)' if member.optional else '')
> +    typ = member.type.doc_type()
> +    return '@item @code{%s%s%s}%s\n' % (
> +        member.name,
> +        ': ' if typ else '',
> +        typ if typ else '',
> +        ' (optional)' if member.optional else '')
>
>
>  def texi_members(doc, what, member_func):
> --
> 2.7.4
>
>
> --
Marc-André Lureau