[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: John Snow
Subject: Re: cleanups with long-term benefits (was Re: [PATCH] schemas: Add vim modeline)
Date: Mon, 3 Aug 2020 16:48:26 -0400
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.10.0

On 8/3/20 3:54 PM, Nir Soffer wrote:
On Mon, Aug 3, 2020 at 9:19 PM John Snow <jsnow@redhat.com> wrote:

On 8/3/20 2:16 PM, Paolo Bonzini wrote:
On 03/08/20 20:10, John Snow wrote:

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:

The current version of the new yaml based schema:

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

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



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

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


This optimizes for writing instead of reading.

Following a "path of least resistance" from the existing QAPI language, clearly carrying over the '*optional' syntax.

     optional: true

Would be nicer to read, but more important is all the tools parsing
this schema in multiple languages that will have code like:

     def is_optional(node):
         return node.name.startswith("?")

Instead of :

    if node.optional:

Or maybe better:

     if node.required:

Because it seems that more nodes are optional, so focusing on the required
items will make the schema shorter and more clear.

        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.

Using | is nicer than >-. Not sure what is the difference. In vdsm we don't use
anything and I think it causes trouble when indenting text.

I believe when I wrote this example I was trying to highlight the different space consumption styles for the purposes of demonstrating what it would do to Sphinx document generation support.

ultimately, there's not really a way to enforce one or the other style post-parse.

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

        type: bool
        default: 'true'

Why is the default a string and not the actual type?

I'm going to be honest: I forget. I was playing around with the idea of documenting defaults for the purposes of documentation, but not necessarily for performing the actual code generation of those defaults.

I believe I specified this field as a string in my grammar and `5` would get promoted to "5", but `true` caused a type error.

Doing something in a type-safe way seemed ... harder. So I didn't.

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

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

        type: 'uint32'
        default: 2

Here you use the real type, and this is nicer.

        doc: >-
          Number of channels when using fixed settings.

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

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

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

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

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

Good example :-)

reply via email to

[Prev in Thread] Current Thread [Next in Thread]