Commit a35c9bf8 authored by Marc-André Lureau's avatar Marc-André Lureau Committed by Markus Armbruster
Browse files

qapi: add 'If:' condition to enum values documentation 



Use a common function to generate the "If:..." line.

While at it, get rid of the existing \n\n (no idea why it was
there). Use a line-break in member description, this seems to look
slightly better in the plaintext version.

Signed-off-by: default avatarMarc-André Lureau <marcandre.lureau@redhat.com>
Message-Id: <20181213123724.4866-19-marcandre.lureau@redhat.com>
Reviewed-by: default avatarMarkus Armbruster <armbru@redhat.com>
Signed-off-by: default avatarMarkus Armbruster <armbru@redhat.com>
parent 8ee06f61

scripts/qapi/doc.py

+16 −9
Original line number Diff line number Diff line
@@ -126,19 +126,27 @@ def texi_body(doc): 
    return texi_format(doc.body.text)





def texi_enum_value(value):

def texi_if(ifcond, prefix='\n', suffix='\n'):

    """Format the #if condition"""

    if not ifcond:

        return ''

    return '%s@b{If:} @code{%s}%s' % (prefix, ', '.join(ifcond), suffix)





def texi_enum_value(value, desc, suffix):

    """Format a table of members item for an enumeration value"""

    return '@item @code{%s}\n' % value.name

    return '@item @code{%s}\n%s%s' % (

        value.name, desc, texi_if(value.ifcond, prefix='@*'))





def texi_member(member, suffix=''):

def texi_member(member, desc, suffix):

    """Format a table of members item for an object type member"""

    typ = member.type.doc_type()

    membertype = ': ' + typ if typ else ''

    return '@item @code{%s%s}%s%s\n' % (

    return '@item @code{%s%s}%s%s\n%s' % (

        member.name, membertype,

        ' (optional)' if member.optional else '',

        suffix)

        suffix, desc)





def texi_members(doc, what, base, variants, member_func):
@@ -155,7 +163,7 @@ def texi_members(doc, what, base, variants, member_func): 
            desc = 'One of ' + members_text + '\n'

        else:

            desc = 'Not documented\n'

        items += member_func(section.member) + desc

        items += member_func(section.member, desc, suffix='')

    if base:

        items += '@item The members of @code{%s}\n' % base.doc_type()

    if variants:
@@ -165,7 +173,7 @@ def texi_members(doc, what, base, variants, member_func): 
            if v.type.is_implicit():

                assert not v.type.base and not v.type.variants

                for m in v.type.local_members:

                    items += member_func(m, when)

                    items += member_func(m, desc='', suffix=when)

            else:

                items += '@item The members of @code{%s}%s\n' % (

                    v.type.doc_type(), when)
@@ -185,8 +193,7 @@ def texi_sections(doc, ifcond): 
            body += texi_example(section.text)

        else:

            body += texi_format(section.text)

    if ifcond:

        body += '\n\n@b{If:} @code{%s}' % ", ".join(ifcond)

    body += texi_if(ifcond, suffix='')

    return body

tests/qapi-schema/doc-good.json

+3 −1
Original line number Diff line number Diff line
@@ -55,7 +55,9 @@ 
#

# @two is undocumented

##

{ 'enum': 'Enum', 'data': [ 'one', 'two' ], 'if': 'defined(IFCOND)' }

{ 'enum': 'Enum', 'data':

  [ { 'name': 'one', 'if': 'defined(IFONE)' }, 'two' ],

  'if': 'defined(IFCOND)' }



##

# @Base:

tests/qapi-schema/doc-good.out

+1 −0
Original line number Diff line number Diff line
@@ -11,6 +11,7 @@ enum QType 
module doc-good.json

enum Enum

    member one

        if ['defined(IFONE)']

    member two

    if ['defined(IFCOND)']

object Base

tests/qapi-schema/doc-good.texi

+1 −1
Original line number Diff line number Diff line
@@ -84,12 +84,12 @@ Examples: 
@table @asis

@item @code{one}

The @emph{one} @{and only@}

@*@b{If:} @code{defined(IFONE)}

@item @code{two}

Not documented

@end table

@code{two} is undocumented





@b{If:} @code{defined(IFCOND)}

@end deftp