From: Marc-André Lureau <marcandre.lureau@redhat.com>

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>
---
 docs/sphinx/qapidoc.py | 14 ++++++++------
 scripts/qapi/common.py |  6 ++++++
 scripts/qapi/schema.py | 10 +++++++++-
 3 files changed, 23 insertions(+), 7 deletions(-)

diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index 511520f33f..d791b59492 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -112,17 +112,19 @@ def _make_section(self, title):
     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
 
diff --git a/scripts/qapi/common.py b/scripts/qapi/common.py
index ba9fe14e4b..5181a0f167 100644
--- a/scripts/qapi/common.py
+++ b/scripts/qapi/common.py
@@ -205,6 +205,12 @@ def cgen_ifcond(ifcond: Union[str, List[str]]) -> str:
     return '(' + ') && ('.join(ifcond) + ')'
 
 
+def docgen_ifcond(ifcond: Union[str, List[str]]) -> str:
+    if not ifcond:
+        return ''
+    return ' and '.join(ifcond)
+
+
 def gen_if(cond: str) -> str:
     if not cond:
         return ''
diff --git a/scripts/qapi/schema.py b/scripts/qapi/schema.py
index f018cfc511..ff9c4f0a17 100644
--- a/scripts/qapi/schema.py
+++ b/scripts/qapi/schema.py
@@ -19,7 +19,12 @@
 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 @@ def __init__(self, ifcond=None):
     def cgen(self):
         return cgen_ifcond(self.ifcond)
 
+    def docgen(self):
+        return docgen_ifcond(self.ifcond)
+
     def is_present(self):
         return bool(self.ifcond)
 
-- 
2.32.0.264.g75ae10bc75

marcandre.lureau@redhat.com writes:

> From: Marc-André Lureau <marcandre.lureau@redhat.com>
>
> 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.

What about a TODO comment?   you suggest a suitable spot?

>
> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>

Hi

On Thu, Aug 5, 2021 at 3:55 PM Markus Armbruster <armbru@redhat.com> wrote:

> marcandre.lureau@redhat.com writes:
>
> > From: Marc-André Lureau <marcandre.lureau@redhat.com>
> >
> > 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.
>
> What about a TODO comment?   you suggest a suitable spot?
>

I don't think this matters much, it will never be a user-friendly text. But
we can leave a comment in the docgen() function to say that the sphinx
build could benefit from a formatted string.



> >
> > Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
>
>
>

-- 
Marc-André Lureau

Marc-André Lureau <marcandre.lureau@gmail.com> writes:

> Hi
>
> On Thu, Aug 5, 2021 at 3:55 PM Markus Armbruster <armbru@redhat.com> wrote:
>
>> marcandre.lureau@redhat.com writes:
>>
>> > From: Marc-André Lureau <marcandre.lureau@redhat.com>
>> >
>> > 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.
>>
>> What about a TODO comment?   you suggest a suitable spot?
>>
>
> I don't think this matters much, it will never be a user-friendly text. But
> we can leave a comment in the docgen() function to say that the sphinx
> build could benefit from a formatted string.

Function docgen_ifcond(), I presume.  Method docgen() is a simple
wrapper.

Something like

    # TODO Doc generated for conditions needs polish