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"

[lornajane]

Field names and entries such as content types should be in backticks, they would be fixed-width fonts if the markdown was rendered (which the comments are not). Values like "Dog" should be double quoted as they are a value rather than a keyword.

[ralfhandl]

Closing as this is now a section in the style guide.