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
