Added CommonMark support to all description #1049
Conversation
versions/3.0.md
Outdated
| @@ -324,7 +324,7 @@ An object representing a Server. | |||
| Field Name | Type | Description | |||
| ---|:---:|--- | |||
| <a name="serverUrl"></a>url | `string` | A URL to the target host. This URL supports Server Variables and may be relative, to indicate that the host location is relative to the location where the OpenAPI definition is being served. Variable substitutions will be made when a variable is named in `{`brackets`}`. | |||
| <a name="serverDescription"></a>description | `string` | An optional string describing the host designated by the URL. | |||
| <a name="serverDescription"></a>description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. | |||
There was a problem hiding this comment.
This implies CommonMark is optional, but it is not.
It is more correct to say, "Description strings are CommonMark text." here and in the remaining changes.
There was a problem hiding this comment.
Going to keep it as-is for now. Will submit a separate PR to remove the word 'optional' from a lot of property descriptions instead as there's no need to mention that.
There was a problem hiding this comment.
I think it is ambiguous and can/should be simplified (more concise, not ambiguous). I'm not referring to the use of the word "optional", but the phrase "can be used", which implies something other than CommonMark can be used if the author does not want rich text. This is CommonMark.
|
My worry is that "Markdown" is a well-known language and calling it "CommonMark" is confusing to me. If it's not to others, this should not stop us from shipping it. |
|
Maybe "This string is Markdown in its CommonMark variant." would be better? |
|
Bikeshedding "This string SHOULD be interpreted as Markdown according to the CommonMark specification."? |
|
This PR was meant to make sure CommonMark can be used in all the descriptions, not to tackle the wording of the |
Fixes #879