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
}
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.
The
@deprecatedtag saysFrom 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.
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
@overridetag could be used to express this.