inconsistent description/string handling

[j-q-arnold]

When reslang generates yaml, it uses inconsistent treatment for the description strings. This causes trouble in the various translations: reslang, yaml, markdown, swagger, html. OpenAPI accepts markdown in the description text. In-line markdown seems to survive reslang ok, but markdown that relies on the start-of-line positioning, such as an example block, doesn't seem to work.

• block treatment varies: >, |, |-. I suggest using the same treatment for all descriptions, so the reslang author can expect consistent treatment.

• Naturally indented strings for attributes retain their indentation. The "extra" lines in the following description keep their extra space in the yaml, causing trouble in the markdown interpretation. Reslang:

  resource x {
  "A textual name under the client's control.
  This value may be used to assign a meaningful name
  to the associated configuration.  The value is not
  required to be unique, but the client is encouraged
  to use the value to identify configurations.
  "
  name: string
  }

  Example yaml:

      name:
        description: |-
          A textual name under the client's control.
              This value may be used to assign a meaningful name
              to the associated configuration.  The value is not
              required to be unique, but the client is encouraged
              to use the value to identify configurations.
  
        type: string

• Descriptions formatted with > have extra linefeeds in the yaml. The raw text is double-spaced. Example:

  - name: Deliver SegmentDeliveryConfiguration
  description: >
    (sync action)  Schedules a delivery for its Segment Delivery
    Configuration.
  
    This creates a `DeliveryAttempt` for the given configuration,
  
    with a `TriggerType.DIRECT_REQUEST` trigger.  The attempt is
  
    scheduled immediately, without affecting automatic schedules.
  
    See also: `DeliveryAttempt`, `TriggerType`

[liveandrew]

hmm interesting - i didn't realize openapi could have markdown in it. i'll have a look at what's going wrong with the translation into yaml. thanks for the details example, it really helps!

[liveandrew]

have fixed this in this way:

1. doc comments now indent based on the 2nd line of text

e.g. "this is a fine comment don't you think james "

will have the first 8 characters of each line stripped off. they will also have the training newline removed

note also that this: " This comment is great"

will have the leading comment removed

finally note that something like this: "This is some code here it comes:

                                                              class Foo {}

"

is still possible via relative indentation of 4 chars

[liveandrew]

some other observations:

2. "block treatment varies: >, |, |-. I suggest using the same treatment for all descriptions, so the reslang author can expect consistent treatment."

this is the yaml formatter and all formatting options are legal in the yaml syntax. it's >- btw. i have no way to force this into a single construct, but i'm genuinely perplexed why we need this given it's just json and it renders fine in swagger

3. "Descriptions formatted with > have extra linefeeds in the yaml. The raw text is double-spaced"

Yes - again, this is yaml syntax with correct treatment. See here for the various options for string encoding: https://symfony.com/doc/current/components/yaml/yaml_format.html#strings

are we having the need to parse these files by hand? all yaml parsers should handle the current representations with no problems