microsoft / microsoft/tsdoc

Should @deprecated be inherited?

Open
#315 0 comments 0 reactions 0 assignees View on GitHub

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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.