[Bug]: multiple @example on an object or property should warn when using OpenAPI emitter

[Arithmomaniac]

Describe the bug

In OpenAPI, parameters, requests, and response all support examples. However, objects and properties only support (a single) example.

Trying to use @example twice in such a case should result in a compilation error., or at least a visible warning.

Reproduction

Playground link. Note that when multiple examples are specified, the last is silently chosen.

Checklist

• Follow our Code of Conduct
• Check that there isn't already an issue that request the same bug to avoid creating a duplicate.
• Check that this is a concrete bug. For Q&A open a GitHub Discussion.
• The provided reproduction is a minimal reproducible example of the bug.

[timotheeguerin]

Do you think you'd want to suppress those warnings here when emitting openapi3(potentially in a lot of place) which might just be one of the emitters you use or that this keeps just being a silent loss of some non critical infomration

[Arithmomaniac]

Timothee Guerin (@timotheeguerin) you're right, I've updated the title accordingly. Here's where I am mentally at the moment:

1. It's logical for there to be multiple examples for a resource, and this could be useful in other emitters (e.g. direct to SDK). So this should not be a compiler error. It follows that there should be some valid behavior in this case for OpenAPI.
2. If a decorator isn't relevant to an emitter at all, no warning is required; not every emitter will support every decorator. However, this case is different - people know one example does something, but they don't know what two examples are supposed to do (take the first? Last? Ignore them, assuming they don't agree with the previous point?).

Putting those together:

• This OpenAPI handling should be explicitly documented somewhere, if it is not already.
• If there are two examples, and if OpenAPI is one of the emitters, then there should be an info/warn-level message in the build, with some sort of config setting (a la Spectre or Roslyn analyzers) to disable it.
  • I would argue that this should show up in the IDE as well.

[wanlwanl]

How about we improve the warn/error message by adding emitter categories, so tsp consumer can by emitter category?