Define style for field names and values in YAML comments / $comment strings

[handrews]

We currently use Markdown formatting in some comments, which doesn't do anything and can (particularly with backtics) read strangely to those not familiar with our variant of Markdown. See PR #4301 for some examples highlighted by @ralfhandl , but I have asked to separate the concern out of that PR since it is a problem in more places than just that.

Sometimes we do want Markdown in field values (because the OAS supports it), but example comments are not one of those places. On the other hand, if we just use the same formatting in example comments for field names that we use for things that aren't field names elsewhere in the spec, that seems a bit confusing, too.

[ralfhandl]

Styles currently used:

# [...] default is `v2`

# The default with "contentEncoding" is application/octet-stream,

# default for primitives without a special format is text/plain

# default for string with binary format is `application/octet-stream`

# default for arrays is based on the type in the `items`
# subschema, which is an object, so `application/json`

# default is `text/plain`

# default based on the `items` subschema would be
# `application/json`, but we want these address objects
# serialized as `application/xml` instead

# default is application/octet-stream, but we can declare
# a more specific image type or types

# The property name 'file' will be used for all files.

# get the `id` field from the request path parameter named `id`

# get the `uuid` field from the `uuid` field in the response body

# returns array of '#/components/schemas/repository'

Cat: # "Cat" will be used as the discriminating value

Dog: # "Dog" will be used as the discriminating value

# all other properties specific to a `Cat`

# all other properties specific to a `Dog`

# all other properties specific to a `Lizard`

I find double-quotes for field names and field values most readable in the rendered YAML examples:

# Use "foo": "bar" consistently

If we want to use one style for YAML comments and $comment field values in JSON files, single-quotes may be easier to write because they don't need escaping:

"$comment": "Use 'foo': 'bar' consistently"