Re: [Qemu-devel] [PATCH 08/11] qapi: Simplify representation of QAPIDoc section text

[Marc-André Lureau]

On Mon, Oct 2, 2017 at 4:13 PM, Markus Armbruster <address@hidden> wrote:
> Use a string instead of a list of strings.
>
> This makes qapi2texi.py generate additional blank lines.  They're
> harmless, and the next commit will get rid of them again.
>
> Signed-off-by: Markus Armbruster <address@hidden>

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


> ---
>  scripts/qapi.py                 | 16 ++++++----------
>  scripts/qapi2texi.py            | 14 +++++++-------
>  tests/qapi-schema/doc-good.texi |  1 +
>  tests/qapi-schema/test-qapi.py  |  6 +++---
>  4 files changed, 17 insertions(+), 20 deletions(-)
>
> diff --git a/scripts/qapi.py b/scripts/qapi.py
> index 2137067b48..e338868a52 100644
> --- a/scripts/qapi.py
> +++ b/scripts/qapi.py
> @@ -106,13 +106,10 @@ class QAPIDoc(object):
>              # optional section name (argument/member or section name)
>              self.name = name
>              # the list of lines for this section
> -            self.content = []
> +            self.text = ''
>
>          def append(self, line):
> -            self.content.append(line)
> -
> -        def __repr__(self):
> -            return '\n'.join(self.content).strip()
> +            self.text += line.rstrip() + '\n'
>
>      class ArgSection(Section):
>          def __init__(self, name):
> @@ -160,7 +157,7 @@ class QAPIDoc(object):
>          # recognized, and get silently treated as ordinary text
>          if self.symbol:
>              self._append_symbol_line(line)
> -        elif not self.body.content and line.startswith('@'):
> +        elif not self.body.text and line.startswith('@'):
>              if not line.endswith(':'):
>                  raise QAPIParseError(self.parser, "Line should end with :")
>              self.symbol = line[1:-1]
> @@ -214,16 +211,15 @@ class QAPIDoc(object):
>
>      def _end_section(self):
>          if self.section:
> -            contents = str(self.section)
> -            if self.section.name and (not contents or contents.isspace()):
> +            text = self.section.text = self.section.text.strip()
> +            if self.section.name and (not text or text.isspace()):
>                  raise QAPIParseError(self.parser, "Empty doc section '%s'"
>                                       % self.section.name)
>              self.section = None
>
>      def _append_freeform(self, line):
>          in_arg = isinstance(self.section, QAPIDoc.ArgSection)
> -        if (in_arg and self.section.content
> -                and not self.section.content[-1]
> +        if (in_arg and self.section.text.endswith('\n\n')
>                  and line and not line[0].isspace()):
>              self._start_section()
>          if (in_arg or not self.section.name
> diff --git a/scripts/qapi2texi.py b/scripts/qapi2texi.py
> index f16fa1ba53..379d27643d 100755
> --- a/scripts/qapi2texi.py
> +++ b/scripts/qapi2texi.py
> @@ -125,7 +125,7 @@ def texi_format(doc):
>
>  def texi_body(doc):
>      """Format the main documentation body"""
> -    return texi_format(str(doc.body)) + '\n'
> +    return texi_format(doc.body.text) + '\n'
>
>
>  def texi_enum_value(value):
> @@ -149,8 +149,8 @@ def texi_members(doc, what, base, variants, member_func):
>      items = ''
>      for section in doc.args.itervalues():
>          # TODO Drop fallbacks when undocumented members are outlawed
> -        if section.content:
> -            desc = texi_format(str(section))
> +        if section.text:
> +            desc = texi_format(section.text)
>          elif (variants and variants.tag_member == section.member
>                and not section.member.type.doc_type()):
>              values = section.member.type.member_names()
> @@ -183,11 +183,10 @@ def texi_sections(doc):
>          if section.name:
>              # prefer @b over @strong, so txt doesn't translate it to *Foo:*
>              body += 'address@hidden:}\n' % section.name
> -        text = str(section)
>          if section.name and section.name.startswith('Example'):
> -            body += texi_example(text)
> +            body += texi_example(section.text)
>          else:
> -            body += texi_format(text)
> +            body += texi_format(section.text)
>      return body
>
>
> @@ -240,7 +239,8 @@ class QAPISchemaGenDocVisitor(qapi.QAPISchemaVisitor):
>              self.out += '\n'
>          if boxed:
>              body = texi_body(doc)
> -            body += 'address@hidden:} the members of @code{%s}' % 
> arg_type.name
> +            body += ('address@hidden:} the members of @code{%s}\n'
> +                     % arg_type.name)
>              body += texi_sections(doc)
>          else:
>              body = texi_entity(doc, 'Arguments')
> diff --git a/tests/qapi-schema/doc-good.texi b/tests/qapi-schema/doc-good.texi
> index a331349756..c032f23fc1 100644
> --- a/tests/qapi-schema/doc-good.texi
> +++ b/tests/qapi-schema/doc-good.texi
> @@ -230,6 +230,7 @@ If you're bored enough to read this, go see a video of 
> boxed cats
>
>  @b{Arguments:} the members of @code{Object}
>
> +
>  @b{Example:}
>  @example
>  -> in
> diff --git a/tests/qapi-schema/test-qapi.py b/tests/qapi-schema/test-qapi.py
> index c7724d3437..fe0ca08d78 100644
> --- a/tests/qapi-schema/test-qapi.py
> +++ b/tests/qapi-schema/test-qapi.py
> @@ -61,8 +61,8 @@ for doc in schema.docs:
>          print 'doc symbol=%s' % doc.symbol
>      else:
>          print 'doc freeform'
> -    print '    body=\n%s' % doc.body
> +    print '    body=\n%s' % doc.body.text
>      for arg, section in doc.args.iteritems():
> -        print '    arg=%s\n%s' % (arg, section)
> +        print '    arg=%s\n%s' % (arg, section.text)
>      for section in doc.sections:
> -        print '    section=%s\n%s' % (section.name, section)
> +        print '    section=%s\n%s' % (section.name, section.text)
> --
> 2.13.6
>
>



-- 
Marc-André Lureau