Commit 09331fce authored by Markus Armbruster's avatar Markus Armbruster
Browse files

qapi: Simplify representation of QAPIDoc section text 



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: default avatarMarkus Armbruster <armbru@redhat.com>
Message-Id: <20171002141341.24616-9-armbru@redhat.com>
Reviewed-by: default avatarMarc-André Lureau <marcandre.lureau@redhat.com>
parent fc3f0df1

scripts/qapi.py

+6 −10
Original line number Diff line number Diff line
@@ -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

scripts/qapi2texi.py

+7 −7
Original line number Diff line number Diff line
@@ -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 += '\n\n@b{%s:}\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 += '\n@b{Arguments:} the members of @code{%s}' % arg_type.name

            body += ('\n@b{Arguments:} the members of @code{%s}\n'

                     % arg_type.name)

            body += texi_sections(doc)

        else:

            body = texi_entity(doc, 'Arguments')

tests/qapi-schema/doc-good.texi

+1 −0
Original line number Diff line number Diff line
@@ -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

tests/qapi-schema/test-qapi.py

+3 −3
Original line number Diff line number Diff line
@@ -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)