### What would you like to be added?

The `description` field is already defined as CommonMark. Now, all strings are acceptable as CommonMark, but this issue is asking for the strings to make obvious sense as CommonMark.

We could also add metadata to comments that are not yet useful CommonMark, and implement a simplification stage that makes such a comment into more renderable CommonMark during OpenAPI generation.

### Why is this needed?

At the moment, consumers of the OpenAPI - for example, generator code that updates https://kubernetes.io/docs/ have to use heuristics to work out whether descriptions are plain text, Markdown, or some hybrid of the two.

---

#### _original issue text was_

~For the OpenAPI specification, add a new field to any definition where a Markdown field description is available.~

- ~this means annotating the doc comments to indicate that they are Markdown~
- ~the `description` OpenAPI field can then either contain the Markdown source, which is kind-of human readable, or it can contain the Markdown transformed into plain text~
Comments that end up in OpenAPI descriptions should be CommonMark
This is a GitHub Issue
repo:kubernetes
owner:kubernetes
Title : Comments that end up in OpenAPI descriptions should be CommonMark
Issue date:

--- start body ---
### What would you like to be added?

The `description` field is already defined as CommonMark. Now, all strings are acceptable as CommonMark, but this issue is asking for the strings to make obvious sense as CommonMark.

We could also add metadata to comments that are not yet useful CommonMark, and implement a simplification stage that makes such a comment into more renderable CommonMark during OpenAPI generation.

### Why is this needed?

At the moment, consumers of the OpenAPI - for example, generator code that updates https://kubernetes.io/docs/ have to use heuristics to work out whether descriptions are plain text, Markdown, or some hybrid of the two.

---

#### _original issue text was_

~For the OpenAPI specification, add a new field to any definition where a Markdown field description is available.~

- ~this means annotating the doc comments to indicate that they are Markdown~
- ~the `description` OpenAPI field can then either contain the Markdown source, which is kind-of human readable, or it can contain the Markdown transformed into plain text~
--- end body ---
