GeezerVison is showing github.com — @deprecated JSDoc tag · Issue #390 · microsoft/TypeScript
@deprecated JSDoc tag #390DescriptionIt would be cool to annotate a method or property with a deprecated attribute
Proposal
If a warning could be issued when using a deprecated method or property it is easier to upgrade to a newer library version (only when the definitions are up to date of course)
Syntax: Same as JSDoc, a simple comment
/**
* @deprecated Use other method
*/
public foo() {
}
If supported in .d.ts files, this would really help with upgrading to a newer version. Reacted by Clay Anderson, Dibran Mulder, Bond, Alex, Igor Minin, Rokas Brazdžionis, Boris Aranovič, binarious, Churakov Andrey, Markus Lindenmann and 279 more Reacted by _al.pt_old, Michael Trouw, Ken, Rémi Chanaud, The web walker, limichange and Roger Padilla Reacted by Ken, The web walker, limichange, Ghislain B., Roger Padilla, Michael Trouw and poseidonCore Reacted by Ken, The web walker, limichange, Roger Padilla and Michael Trouw ActivityRyanCavanaugh commented on Aug 7, 2014 How would this flow through the type system?
interface X {
/*
* @deprecated Use DoOtherThing instead
*/
doThing(): void;
}
interface Y {
/*
* Still supported
*/
doThing(): void;
}
class Z implements X, Y {
doThing() {}
}
var g = new Z();
g.doThing(); // OK? Not OK?Presumably you'd be able to mark a single overload (but not others) as deprecated; would referencing (but not calling) a function with a deprecated overload be an error? Reacted by lilezek, HermannGruber, ExE Boss, Moritz Mahringer, Mikhail Udalov, stefnotch, fregante, Luke, Ilya V., Luis Custodio and 3 more Reacted by Amit Beckenstein DickvdBrink commented on Aug 7, 2014 ContributorAuthor More actions Hmz, tricky question.. didn't thought about this one actually.
Maybe it is only an error in this case when calling it like this:
var x: X = new Z();
x.doThing() // it selected to @deprecated methode so error
var y: Y = new Z();
x.doThing() // still supporter, no error Not really sure though, feels a bit error prone... Reacted by OldStarchy Reacted by 浊酒 JustinBeckwith commented on Jan 6, 2015 C# will allow what you've written above, because it does not react to [Obsolete] attributes on interfaces - only base class implementations. Given the lack of multiple inheritence, this isn't really an issue. Here's how it's handled in C#:
class Program
{
static void Main(string[] args)
{
var x = new Zoo();
// doThing is allowed, even though it is obsolete on interface X
x.doThing();
// doStuff is not allowed. It is not obsolete on the interface, but is obsolete on the base class.
x.doStuff();
Console.Read();
}
}
interface X
{
/// <summary>
///
/// </summary>
[Obsolete("boo", true)]
void doThing();
}
interface Y
{
void doThing();
void doStuff();
}
class Zoo : ZooBase, X
{
public void doThing()
{
Console.WriteLine("boo");
}
[Obsolete]
public override void doStuff()
{
Console.WriteLine("boo");
}
}
abstract class ZooBase
{
[Obsolete("boo", true)]
public abstract void doStuff();
}Reacted by Steven, Florian Rappl, PeterGabriel2 and Shinigami mhegazy commented on Jan 12, 2015 I think this is fair. the class provided a re-declaration of the method. if you were to use the interface directly you would get an error:
var g = new Z();
g.doThing(); // OK, this is the class definition of doThing()
var e: X = new Z();
e.doThing(); // Error, X.doThing() is deprecated. Now consider this:
interface Person {
name: string;
/** @deprecated use birthDate instead */
age?: number;
birthDate?: Date;
}
declare function doStuff(p: Person): void;
// should calling doStuff with age instead of birthDate be an error:
doStuff({
name: "Joe",
age: 25 // Error?: Person.age is depreciated
});if the answer is yes, then the above example should be an error on the extends clause, prohibiting the implementation of a depreciated method on the interface.
it also means you can not depreciate a non-optional member of an interface, cause how else would you use it. louy commented on Nov 27, 2015 I believe this shouldn't cause an error but rather a warning.
For the situation Ryan Cavanaugh (@RyanCavanaugh) mentioned, a function would only be deprecated if there doesn't exist any non-deprecated implementation.
As for implementing an interface-deprecated method in a class, you should get a warning once in the class implementation, not each time you're calling the method.
interface IX {
@deprecated
function doSomething(): void;
}
class X implements IX {
function doSomething(): void; // Warning: IX.doSomething is deprecated
@deprecated
function doSomethingElse(): void;
}
const x = new X();
x.doSomething(); // Ok...
x.doSomethingElse(); // Warning: X.doSomethingElse is deprecatedReacted by csha, Anton Bessonov, Nikolas Bousios, Max and Joseph McMurray kitsonk commented on Nov 27, 2015 That syntax collides with decorators. 😦
Considering this hasn't seen any action in a long time, and now that the compiler parses and integrates JSDoc, it could in theory understand and warn on /* @depecrated */ JSDoc, but is there yet the concept of warning in TypeScript or does it still consider everything an error?
Otherwise this should be the domain of something like tslint Adi Dahiya (@adidahiya), thoughts? Reacted by Felix Becker, Yawar Amin, csha, Lea Reimann and Tim Ritzer louy commented on Nov 27, 2015 Yeah I know. I didn't know that the complier considered JSDoc comments. I thought we might have a reserved keyword or something.
I also think this is beyond the scope of tslint. Linting should be about coding style, not type checking.
AFAIK TS has no concept of warnings. In my opinion however, it should. Similar to ESLint's error/warning concepts. Reacted by Gary Gozlan Reacted by Szymon kitsonk commented on Nov 27, 2015
Linting should be about coding style, not type checking.
I disagree... It should be about things deal with code quality, things that are syntactical errors. tslint and other linting tools do lots of quality checking, like unused variables, conditional assignments, switch statement drop through and defaults, etc.
In fact we draw the defenition from the UNIX lint tool which:
In computer programming, lint is a Unix utility that flags some suspicious and non-portable constructs (likely to be bugs) in C language source code; generically, lint or a linter is any tool that flags suspicious usage in software written in any computer language.
Reacted by Felix Becker, Karol Mierzejewski, Junyoung/"Clare" Jang, ExE Boss, Szymon and Debajyoti Bhaumik louy commented on Nov 27, 2015 felixfbecker commented on Mar 27, 2016 I also think this is something that does not need a language feature, but belongs to documentation (jsdoc) and can be checked by something like tslint. Reacted by AA, xdvarpunen, Florian Wendelborn, Devin Rhode and Henry Chan Reacted by ikokostya, mdcorriveau, Tanguy Krotoff, Haroen Viaene, Itrulia, Carlos Gomes Martinho, Christian d'Heureuse, Junyoung/"Clare" Jang, John Haugeland, stunaz and 14 more changed the title [-]Deprecated attribute[/-] [+]@deprecated JSDoc Attribute[/+] on Apr 10, 2020changed the title [-]@deprecated JSDoc Attribute[/-] [+]@deprecated JSDoc tag[/+] on Apr 10, 2020Kingwl commented on May 13, 2020 I'd like to work on this both ts and vscode side. Reacted by Donald Pipowitch, limichange, Denis Bendrikov, Joseph Kohlmann, Ghislain B., Glen, Anton Fedchenko and Ken luke-john commented on Jun 10, 2020 It's unclear to me from this proposal whether deprecating an entry in a union would be supported.
type Props = {
value:
| 'a'
| 'one'
/** @deprecated */
| 'value-one'
}If so great 👍. If not would it be possible to include that in this proposal or would it be better to create a separate proposal? Reacted by Holger Jeromin, Vincent Ricard, Daniel Knaust, Evan Jacobs, zhao5363, recordare, Demian Ferreiro, ExE Boss, Hays Clark, Karol Majewski and 9 more JasonHK commented on Jun 10, 2020
It's unclear to me from this proposal whether deprecating an entry in a union would be supported.
type Props = {
value:
| 'a'
| 'one'
/** @deprecated */
| 'value-one'
}If so great 👍. If not would it be possible to include that in this proposal or would it be better to create a separate proposal?
Luke John (@luke-john) I think union and insertion type members don't support TSDoc at all. luke-john commented on Jun 10, 2020 Reacted by Demian Ferreiro ghiscoding commented on Sep 19, 2020 Since this is now a thing, it could be removed from Roadmap Future section
Investigate Ambient, Deprecated, and Conditional decorators
haysclark commented on Sep 24, 2020
Since this is now a thing, it could be removed from Roadmap Future section
Investigate Ambient, Deprecated, and Conditional decorators
Before Deprecated is removed from the Roadmap, it would be great to learn more about the possibility of supporting deprecated Unions. IMHO, this is an extremely common User Case which Luke John (@luke-john) also mentioned above.
e.g.
/** @deprecated */
type LegacySizes =
| "sm"
| "lg";
export type ButtonSizes =
| LegacySizes
| "small"
| "medium"
| "large";
export interface ButtonProps {
size?: ButtonSizes;
}Reacted by John Grishin, Celo Reis, Andrei Lozhkin, Jason Kwok, Mark McDermid, juanvargas, Gabriele Tomberli, Rob Wierzbowski, Thom Wheeler, Cameron Moon and 7 more devinrhode2 commented on Apr 14, 2021 Is this supported now? If so where are the docs for this? (Or can anyone share an example?) NateScarlet commented on Apr 14, 2021 Reacted by Davide Campello Reacted by Devin Rhode SebastianStehle commented on Jul 25, 2021 Is it possible to mark all deprecated warnings? HolgerJeromin commented on Aug 11, 2021 Reacted by Nathan Shively-Sanders, Arti Villa and Chris Kuech xiaoxiangmoe commented on Feb 27, 2022
MetadataMetadataDevelopmentNo branches or pull requestsIssue actions
|
