Re: cleanups with long-term benefits (was Re: [PATCH] schemas: Add vim modeline)

[Paolo Bonzini]

On 03/08/20 20:10, John Snow wrote:
> Heresy:
> 
> Docstrings could become part of the data format so they can be parsed,
> analyzed and validated. Parsers largely treat comments like non-semantic
> information and discard it. Round-trip parsers that preserve comments in
> any language are extremely rare.
> 
> If the docstrings are relevant to the generator and aren't discardable,
> they should be fully-fledged data members.
> 
> In a prototype I had for a YAML format, I just promoted docstrings
> directly to fields, so I could allow clients to query help text for
> individual commands.

This would be actually a good idea, but somebody has to write the code.
 Each field's docstring should be attached to the field, however---no
parsing needed only looking at the tree.  Take a look at what Nir posted:

> Here is the patch adding schema convertor from qemu "json" format to
> standard yaml:
> https://github.com/oVirt/vdsm/commit/e57b69e72987c0929b20306c454835b52b5eb7ee
> 
> The current version of the new yaml based schema:
> https://github.com/oVirt/vdsm/blob/master/lib/vdsm/api/vdsm-api.yml


    VmDiskDevice: &VmDiskDevice
        added: '3.1'
        description: Properties of a VM disk device.
        name: VmDiskDevice
        properties:
        -   description: Indicates if writes are prohibited for the
                device
            name: readonly
            type: boolean

        -   description: The size of the disk (in bytes)
            name: apparentsize
            type: uint

etc.

Paolo