qapidoc: introduce QAPISchemaIfCond.docgen()

Instead of building the condition documentation from a list of string,
use the result generated from QAPISchemaIfCond.docgen().

This changes the generated documentation from:
- COND1, COND2... (where COND1, COND2 are Literal nodes, and ',' is Text)
to:
- COND1 and COND2 (the whole string as a Literal node)

This will allow us to generate more complex conditions in the following
patches, such as "(COND1 and COND2) or COND3".

Adding back the differentiated formatting is left to the wish list.

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Message-Id: <20210804083105.97531-6-marcandre.lureau@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[TODO comment added]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
This commit is contained in:
Marc-André Lureau 2021-08-04 12:31:00 +04:00 committed by Markus Armbruster
parent 6cc2e4817f
commit d806f89f87
3 changed files with 24 additions and 7 deletions

View File

@ -112,17 +112,19 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor):
def _nodes_for_ifcond(self, ifcond, with_if=True):
"""Return list of Text, literal nodes for the ifcond
Return a list which gives text like ' (If: cond1, cond2, cond3)', where
the conditions are in literal-text and the commas are not.
Return a list which gives text like ' (If: condition)'.
If with_if is False, we don't return the "(If: " and ")".
"""
condlist = intersperse([nodes.literal('', c) for c in ifcond.ifcond],
nodes.Text(', '))
doc = ifcond.docgen()
if not doc:
return []
doc = nodes.literal('', doc)
if not with_if:
return condlist
return [doc]
nodelist = [nodes.Text(' ('), nodes.strong('', 'If: ')]
nodelist.extend(condlist)
nodelist.append(doc)
nodelist.append(nodes.Text(')'))
return nodelist

View File

@ -205,6 +205,13 @@ def cgen_ifcond(ifcond: Union[str, List[str]]) -> str:
return '(' + ') && ('.join(ifcond) + ')'
def docgen_ifcond(ifcond: Union[str, List[str]]) -> str:
# TODO Doc generated for conditions needs polish
if not ifcond:
return ''
return ' and '.join(ifcond)
def gen_if(cond: str) -> str:
if not cond:
return ''

View File

@ -19,7 +19,12 @@ import os
import re
from typing import Optional
from .common import POINTER_SUFFIX, c_name, cgen_ifcond
from .common import (
POINTER_SUFFIX,
c_name,
cgen_ifcond,
docgen_ifcond,
)
from .error import QAPIError, QAPISemError, QAPISourceError
from .expr import check_exprs
from .parser import QAPISchemaParser
@ -32,6 +37,9 @@ class QAPISchemaIfCond:
def cgen(self):
return cgen_ifcond(self.ifcond)
def docgen(self):
return docgen_ifcond(self.ifcond)
def is_present(self):
return bool(self.ifcond)