Commit 860e8778 authored by Markus Armbruster's avatar Markus Armbruster
Browse files

qapi: Conjure up QAPIDoc.ArgSection for undocumented members 



qapi2texi.py already conjures up ArgSections for undocumented
enumeration values, in texi_enum.  Drop that, and conjure them up for
all kinds of "arguments" (enumeration values, object and alternate
type members) in qapi.py instead.

Take care to keep generated documentation exactly the same for now.

Signed-off-by: default avatarMarkus Armbruster <armbru@redhat.com>
Reviewed-by: default avatarEric Blake <eblake@redhat.com>
Message-Id: <1489582656-31133-16-git-send-email-armbru@redhat.com>
parent 069fb5b2

scripts/qapi.py

+2 −3
Original line number Diff line number Diff line
@@ -224,8 +224,7 @@ class QAPIDoc(object): 
    def connect_member(self, member):

        if member.name not in self.args:

            # Undocumented TODO outlaw

            pass

        else:

            self.args[member.name] = QAPIDoc.ArgSection(member.name)

        self.args[member.name].connect(member)

scripts/qapi2texi.py

+16 −15
Original line number Diff line number Diff line
@@ -123,7 +123,7 @@ def texi_format(doc): 
    return "\n".join(lines)





def texi_body(doc):

def texi_body(doc, only_documented=False):

    """

    Format the body of a symbol documentation:

    - main body
@@ -131,17 +131,21 @@ def texi_body(doc): 
    - followed by "Returns/Notes/Since/Example" sections

    """

    body = texi_format(str(doc.body)) + "\n"

    if doc.args:

        body += "@table @asis\n"

        for arg, section in doc.args.iteritems():



    args = ''

    for name, section in doc.args.iteritems():

        if not section.content and not only_documented:

            continue        # Undocumented TODO require doc and drop

        desc = str(section)

        opt = ''

        if section.optional:

            desc = re.sub(r'^ *#optional *\n?|\n? *#optional *$|#optional',

                          '', desc)

            opt = ' (optional)'

            body += "@item @code{'%s'}%s\n%s\n" % (arg, opt,

                                                   texi_format(desc))

        args += "@item @code{'%s'}%s\n%s\n" % (name, opt, texi_format(desc))

    if args:

        body += "@table @asis\n"

        body += args

        body += "@end table\n"



    for section in doc.sections:
@@ -183,10 +187,7 @@ def texi_union(expr, doc): 


def texi_enum(expr, doc):

    """Format an enum to texi"""

    for i in expr['data']:

        if i not in doc.args:

            doc.args[i] = qapi.QAPIDoc.ArgSection(i)

    body = texi_body(doc)

    body = texi_body(doc, True)

    return TYPE_FMT(type="Enum",

                    name=doc.symbol,

                    body=body)