Re: [PATCH v4 04/46] qapi: modify docstrings to be sphinx-compatible

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> On 9/30/20 4:47 AM, Markus Armbruster wrote:
>> Sadly, the fact that start_if() and end_if() are functions isn't
>> immediately obvious anymore.
>> I've seen :func:`start_if` elsewhere.  Is this something we should
>> or
>> want to use?
>
> Looks like `start_if()` works just fine too. If you are hard-set in
> wanting to see those parentheses I can use this style, but admit I am 
> not likely to use them myself in newer docstrings, and there's no way
> to enforce their presence OR absence that I am aware of.

Well, there's no way to enforce presence or absence of ` either, right?

Aside: checking the enclosed text resolves as a cross-reference could
provide good-enough enforcement of absence, but enclosing stuff in `
when you shouldn't is probably the lesser issue.

> I'll bake that change in for now until I see another reply.

Since this is a side show right now, consider the arguments raised so
far, use your judgement, and move on to the main show.