Open johanste opened 2 years ago
@richdoc("{name}", <type-with-name>)
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.
I think the answer here is to just state that @doc/doc comments can support markdown -- we could treat it as a documentation issue.
Implementation issue for beta is just documentation, per Mike's comment and discussion
est: 1, pri: 2
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
@richDoc
decorator for rich documentation that takes a format parameter. The only supported value (for now) isCommonMark
.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:
CommonMark
), as well as different dialects within a dialect. Is it enough to support justCommonMark
?