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

[John Snow <jsnow@redhat.com>]

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'