microsoft / microsoft/typespec

Support including parent type's documentation in child type doc comments

Open
#10,488 2 comments 0 reactions 0 assignees View on GitHub
compiler:core design:needed triaged:core
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.