Should @deprecated be inherited?
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 5k
- Forks
- 162
- Avg merge
- 17h 24m
- Merged PRs (30d)
- 8
Description
The @deprecated tag says
It recursively applies to members of the container. For example, if a class is deprecated, then so are all of its members.
From the specification, it's not clear whether "recursively" applies to inheritance or merely shallow containment. In TypeScript's implementation of TSDoc today, field declarations do not inherit the deprecation status from their parent.
class Base {
/** @deprecated Please don't use this field! */
count = 0;
}
class Child extends Base {
count = 1; // TypeScript says this field is **not** deprecated
}
In https://github.com/microsoft/TypeScript/issues/47937 we see both sides of the story. One example where inheritance is desirable and one example where it's not desirable.
The goal is this issue resolve the question of what the intended behavior is today, so that we can update the specification and achieve consistent understanding across implementations.
Personal Opinion
I think the most useful default is to inherit. It's the simplest mental model.
If users want to override the default behavior and forcefully shadow a deprecated member, they should be able to do so via explicit tagging, i.e. an escape hatch. Maybe the @override tag could be used to express this.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with pages/tags/deprecated.md and compare its wording about recursive application with TypeScript issue #47937 and the linked examples. Resolve whether deprecation should cross inheritance or only containment, then update the specification so implementations have consistent guidance.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100