IntelliSense: Support @deprecated tag

[Zlatkovsky]

Suppose that I am a library author, and in V1.0 of my APIs I have the following method signature:

namespace MyLibrary {
    export class SomeObject {
        foo(text: string): void { 
            alert(text); 
        }
    }   
}

After my V1.0 API is released, I receive feedback that foo wasn't that descriptive of a name (should have used bar!)... or perhaps that I should instead have made it a static method off of MyLibrary, such as MyLibrary.performFoo(new SomeObject());.

Based on that feedback, I wish I would have named the method differently, so that new users of my V1.1+ API and above never see foo, but see my new and improved API signature instead. On the other hand, I certainly don't want to break the compilation of existing projects that use foo.

Suggestion: In the ideal world, I wish I could add a @deprecated tag to foo that would be recognized by the TypeScript compiler / language service, and where the behavior would be:

• foo is not visible by default in the SomeObject's IntelliSense, but continues to be usable by the compiler.
• [As icing on the cake]: foo's declaration does show up if the developer has already typed the complete method's name (i.e., new MyLibrary.SomeObject().foo), so that -- in pressing ctrl+space -- he/she can still see foo's parameters, if they're already using the deprecated version of the function (and that way, too, they can see the @deprecated tag, along with a library-author-supplied description of what new method to use instead).

[aluanhaddad]

@Zlatkovsky you may be interested in #2900

[DickvdBrink]

Refs #390

[mhegazy]

closing in favor of #390