Re: [PATCH v7 05/10] qapidoc: introduce QAPISchemaIfCond.docgen()

[Markus Armbruster]

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