Add documentation to @doc and other documentation components that they could contain markdown or other formatting

[johanste]

Rich text formatting in descriptions/documentation

Documentation for APIs often involve more than just raw text. Common reasons to use rich text formatting include rendering of tables or embedding links into the generated reference documentation.

For an example, see the APIM List By Tags endpoint which illustrates the attempt to use (valid) openapi descriptions that contains a table in the API documentation as well as the issue with tools treating description fields as plain text (broken rendering).

OpenAPI support for rich text

OpenAPI allows for rich text formatting in description fields using CommonMark. As evident from the example above, there are gaps in our toolset with regards to how rich text is handled.

Possible solution

• Only support CommonMark for input.
• Add new @richDoc decorator for rich documentation that takes a format parameter. The only supported value (for now) is CommonMark.

@richDoc(
"""
|One|Two|
|-|-|
|1|2|
|3|4|
""", "CommonMark")
model ModelWithTableDocs {};

Alternate solution

Change the @doc decorator so that it accepts CommonMark instead of raw text. For the most part, that is an extension to its current decorator definition (in most cases, you don't have accidental markup in the raw text), but it adds complexity to emitters since they have to sniff the format/convert to something they can manage or risk broken rendering as shown above.

Challenges/questions:

• There are many rich language definitions *in adition to CommonMark), as well as different dialects within a dialect. Is it enough to support just CommonMark?
• Client and service library code emitters want to emit descriptions as docstring/comments in generated code. Some langauges (e.g. Python) have idiomatic formats for rich text (in the case of Python, reStructuredText) but most languages expect plain text in their descriptions. Do we expect multiple formats in the specification or do we provide converters?

[markcowl]

Notes from design meeting

• Team is leaning toward format-specific decorators, rather than a format parameter
• Agreed that we should use the second (optional) parameter for value substitution in the document string @richdoc("{name}", <type-with-name>)
• Broaden proposal to include all the doc types and how we would represent
  • documentation types we would present
    • textual documentation
    • formatted documentation (commonMark, Html, others?)
    • example values
    • operation examples
    • external documentation files
  • how these map into different documentation targets
  • What we need for internal documents (include in azure-specific libraries)
  • What we should surface to external users in the core

[tjprescott]

From the most recent review with the API review board, they weren't a fan of HTML in the docstrings and would prefer something like markdown.

[mikekistler]

I think the answer here is to just state that @doc/doc comments can support markdown -- we could treat it as a documentation issue.

[markcowl]

Implementation issue for beta is just documentation, per Mike's comment and discussion

[markcowl]

est: 1, pri: 2