On Fri, 7 Feb 2020 at 14:43, Markus Armbruster <arm...@redhat.com> 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
