Re: [PATCH 08/29] qapi: Use ':' after @argument in doc comments

[Peter Maydell]

On Fri, 7 Feb 2020 at 14:43, Markus Armbruster <address@hidden> wrote:


> Here's a style I'd dislike less:
>
>     # @file: Node to create the image format on
>     #
>     # @size: Size of the virtual disk in bytes
>     #
>     # @log-size: Log size in bytes, must be a multiple of 1 MB
>     #     (default: 1 MB)
>     #
>     # @block-size: Block size in bytes, must be a multiple of 1 MB and not
>     #     larger than 256 MB (default: automatically choose a block
>     #     size depending on the image size)
>     #
>     # @subformat: vhdx subformat (default: dynamic)
>     #
>     # @block-state-zero: Force use of payload blocks of type 'ZERO'.
>     #     Non-standard, but default.  Do not set to 'off' when using
>     #     'qemu-img convert' with subformat=dynamic.

The problem with this one is that there's no way for the
doc-comment parser to know how far lines 2,3... are
supposed to be indented. Unlike the block-quote issue, this
is a real problem, because it's not possible to distinguish:

# @foo: - Here's a bulleted list
#         Line 2 of the list item should indent to match the first
# @bar: - A one item list
#       A line not in the list

which is the kind of thing that will show up in real-world
usage. (Unless you wanted to say "always 4-space indent" or something,
which I think would tend to result in a lot of accidental
over-indentation and unintended blockquotes in the output.)

> Or maybe even
>
>     # @file:
>     # Node to create the image format on
>     #
>     # @size:
>     # Size of the virtual disk in bytes
>     #
>     # @log-size:
>     # Log size in bytes, must be a multiple of 1 MB (default: 1 MB)
>     #
>     # @block-size:
>     # Block size in bytes, must be a multiple of 1 MB and not larger
>     # than 256 MB (default: automatically choose a block size depending
>     # on the image size)
>     #
>     # @subformat:
>     # vhdx subformat (default: dynamic)
>     #
>     # @block-state-zero:
>     # Force use of payload blocks of type 'ZERO'.  Non-standard, but
>     # default.  Do not set to 'off' when using 'qemu-img convert' with
>     # subformat=dynamic.

Conveniently this patchset already supports this format :-)
You can write either

# @foo: bar
#       baz
#         indented

or
# @foo:
# bar
# baz
#   indented

and they'll come out to the same thing (the parser.py code
sends the same doc strings to the rST visitor).

thanks
-- PMM