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

[John Snow]

On 8/3/20 2:16 PM, Paolo Bonzini wrote:
> 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

I was working on a small prototype that used something that looked like 
this; the "*opt" format was traded for "?opt", but otherwise:


struct:
  name: AudiodevPerDirectionOptions
  doc: >
    General audio backend options that are used for both
    playback and recording.
  since: '4.0'
  members:

    ?mixing-engine:
      type: bool
      default: 'true'
      since: '4.2'
      doc: |
        Use QEMU's mixing engine to mix all streams inside QEMU and
        convert audio formats when not supported by the backend.

        When set to off, fixed-settings must be also off.

    ?fixed-settings:
      type: bool
      default: 'true'
      doc: >-
        Use fixed settings for host input/output.
        When off, frequency, channels and format must not be specified.

    ?frequency:
      type: bool
      default: '44100'
      doc: >-
        frequency to use when using fixed settings.

    ?channels:
      type: 'uint32'
      default: 2
      doc: >-
        Number of channels when using fixed settings.

    ?voices:
      type: 'uint32'
      default: 1
      doc: "Number of voices to use."

    ?format:
      type: 'AudioFormat'
      default: 's16'
      doc: "Sample format to use when using fixed settings."

    ?buffer-length:
      type: 'uint32'
      doc: 'The buffer length, in microseconds.'

  features:
    my-cool-feature:
      since: '6.0'
      doc: 'This is, no doubt, an extremely cool feature.'

    my-bad-feature:
      doc: 'This is a very bad feature. I am sorry for making it.'
      since: '1.0'
      deprecated: '5.9'