Answering myself, this introduces serious problems:
- Dual Description Ambiguity
It's unclear which one to display by default. Always showing both is
redundant in most cases since they often contain the same text.
The documentation generator (format.rs) now needs to make decisions
about precedence that weren't necessary before.
- Macro Syntax Confusion
The current #[api] macro doesn't clearly distinguish between:
- type-description: describing the type itself
- property-description: describing this specific usage of the type
- Rare Use Case
The scenario where we actually need different descriptions for the same
type used in different properties is uncommon. In the rare cases where
this is needed, defining two separate schema types is a simpler and
more explicit solution.
So I guess it is not worth to implement it.
- Dietmar
