microsoft / microsoft/typespec
Support including parent type's documentation in child type doc comments
- Dominant language
- Java
- Stars
- 5.9k
- Forks
- 394
- Avg merge
- 1d 23h
- Merged PRs (30d)
- 104
Description
### Clear and concise description of the problem
When a scalar extends another scalar, documentation is inherited if the child has no doc. But adding a doc comment to the child to provide additional context replaces the parent's documentation entirely.
```tsp
/** A unique identifier for a resource. */
scalar ResourceId extends string;
/** Refers to a user in the system. */
scalar UserId extends ResourceId;
// UserId's doc is only "Refers to a user in the system."
// "A unique identifier for a resource." is lost.
```
Today the only option is to copy-paste the parent's text into every child, which is fragile and doesn't scale across a type hierarchy.
A tag like `{@inheritDoc}` (similar to TSDoc) would let authors inline the parent's documentation at a controlled position:
```tsp
/** {@inheritDoc} Refers to a user in the system. */
scalar UserId extends ResourceId;
// Result: "A unique identifier for a resource. Refers to a user in the system."
```
This could apply to any type with inheritance (scalars, models).
### Checklist
- [x] Follow our [Code of Conduct](https://github.com/microsoft/typespec/blob/main/CODE_OF_CONDUCT.md)
- [x] Read the [docs](https://typespec.io/docs/).
- [x] Check that there isn't already an issue that request the same feature to avoid creating a duplicate.
Contributor guide
Assessment
This issue has not been assessed yet.