Re: [PATCH 29/42] qapi: Add "Details:" disambiguation marker

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> This clarifies sections that are mistaken by the parser as "intro"
> sections to be "details" sections instead.
>
> Signed-off-by: John Snow <jsnow@redhat.com>

This is rather terse.

Why does the boundary between "intro" (previously "body") and "details"
matter?  As far as I understand, it matters for inlining.

What is inlining?

The old doc generator emits "The members of T" into the argument
description in the following cases:

* When a command's arguments are given as a type T, the doc comment has
  no argument descriptions, and the generated argument description
  becomes "The members of T".

* When an object type has a base type T, "The members of T" is appended
  to the doc comment's (possibly empty) argument descriptions.

* For union types, "The members of T when TAG is VALUE" is appended to
  the doc comment's argument descriptions for every tag VALUE and
  associated type T.

We want a description of the members of T right there instead.  To get
it right there, we need to inline from T's documentation.

What exactly do we need to inline?  Turns out we don't want "intro", we
do want the argument descriptions and other stuff we can ignore here.

"intro" ends before the argument descriptions, features, or a tagged
section, whatever comes first.  Most of the time, this works fine.  But
there are a few troublesome cases.  Here's one:

    ##
    # @MemoryBackendShmProperties:
    #
    # Properties for memory-backend-shm objects.
    #
    # This memory backend supports only shared memory, which is the
    # default.
    #
    # Since: 9.1
    ##
    { 'struct': 'MemoryBackendShmProperties',
      'base': 'MemoryBackendProperties',
      'data': { },
      'if': 'CONFIG_POSIX' }

Everything up to "Since:" is "intro".  Consequently, the old doc
generator emits "The members of MemoryBackendProperties" right there:

    "MemoryBackendShmProperties" (Object)
    -------------------------------------

    Properties for memory-backend-shm objects.

    This memory backend supports only shared memory, which is the default.


    Members
    ~~~~~~~

    The members of "MemoryBackendProperties"

    Since
    ~~~~~

    9.1


    If
    ~~

    "CONFIG_POSIX"

That's also where the new one inlines.  Okay so far.

This gets in turn inlined into ObjectOptions for branch
memory-backend-shm.  Since we don't inline "intro", we don't inline
"This memory backend supports only shared memory, which is the default."
That's a problem.

This patch moves the boundary between "intro" and the remainder up that
paragraph, so we don't lose that line.  It accomplishes that by giving
us syntax to manually mark the end of "intro"

However, your solution is manual: it gives us the means[*] to mark the
boundary with "Details:" to avoid loss of text.  What if we don't
notice?  Should we tweak the syntax to force us to be explicit?  How
many doc comments would that affect?


[*] Actually, we have means even before this patch, they're just ugly.
See the TODO comment added in commit 14b48aaab92 (qapi: convert
"Example" sections without titles).