qapi: [RFC] Doc comment convention for @arg: sections

[Markus Armbruster]

The QAPI schema doc comment language provides special syntax for command
and event arguments, struct and union members, alternate branches,
enumeration values, and features: "sections" starting with @arg:.

By convention, we format them like this:

    # @arg: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
    #       do eiusmod tempor incididunt ut labore et dolore magna
    #       aliqua.

Okay for names as short as "name", but we have much longer ones.  Their
description gets squeezed against the right margin, like this:

    # @dirty-sync-missed-zero-copy: Number of times dirty RAM synchronization 
could
    #                               not avoid copying dirty pages. This is 
between
    #                               0 and @dirty-sync-count * @multifd-channels.
    #                               (since 7.1)

The description is effectively 50 characters wide.  Easy enough to read,
but awkward to write.

The awkward squeeze against the right margin makes people go beyond it,
which produces two undesirables: arguments about style, and descriptions
that are unnecessarily hard to read, like this one:

    # @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU.  This 
is
    #                           only present when the postcopy-blocktime 
migration capability
    #                           is enabled. (Since 3.0)

Ugly, too.

I'd like to change the convention to

    # @arg:
    #     Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
    #     do eiusmod tempor incididunt ut labore et dolore magna aliqua.

    # @dirty-sync-missed-zero-copy:
    #     Number of times dirty RAM synchronization could not avoid
    #     copying dirty pages.  This is between 0 and @dirty-sync-count
    #     * @multifd-channels.  (since 7.1)

    # @postcopy-vcpu-blocktime:
    #     list of the postcopy blocktime per vCPU.  This is only present
    #     when the postcopy-blocktime migration capability is
    #     enabled.  (Since 3.0)

We may want to keep short descriptions one the same line, like

    # @multifd-bytes: The number of bytes sent through multifd (since 3.0)

We could instead do

    # @arg: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
    #     do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Another option would be

    # @arg:
    # Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
    # eiusmod tempor incididunt ut labore et dolore magna aliqua.

or even

    # @arg: Lorem ipsum dolor sit amet, consectetur adipiscing elit,
    # sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

but I find these less readable.

A bulk reformatting of doc comments will mess up git-blame, which will
be kind of painful[*].  But so is the status quo.

Thoughts?



[*] Yes, I'm aware of (and grateful for) --ignore-rev & friends.  It's
still kind of painful.