How to deprecate a single parameter

[JoshuaKGoldberg]

palantir/tslint#4281 is an example of a scenario where a single parameter is deprecated: moving from multiple standalone arguments to a single arguments object, while maintaining backwards compatibility.

Can we mark just that parameter as deprecated? Something like:

export interface IFormatter {
    /**
     * Formats linter results
     * @param failures - Linter failures that were not fixed
     * @param @deprecated fixes - Fixed linter failures. Available when the `--fix` argument is used on the command line. 
     */
    format(failures: RuleFailure[], fixes?: RuleFailure[]): string;
}

[octogonz]

Hmm... I find it odd to deprecate only part of an API signature. Would this be a better approach?

export interface IFormatter {
    /**
     * Formats linter results
     * @param failures - Linter failures that were not fixed
     */
    format(failures: RuleFailure[]): string;

    /**
     * @deprecated Use {@link IFormatter.(format:1)} instead.
     */
    format(failures: RuleFailure[], fixes?: RuleFailure[]): string;
}

This way the new contract and deprecated contract are each clearly described.

Also it follows our standard convention that @deprecated should always include a recommendation of what to use instead.

[JoshuaKGoldberg]

That's a great suggestion, thanks @pgonzal! I can't think of a situation off the top of my head in which this wouldn't be doable, but will try.

[snebjorn]

I've noticed an issue. @deprecated will affect the overloads.

In the below func(a) is also marked as @deprecated

interface Foo {
  /** @deprecated */
  func(a, b);
  func(a);
}

This can easily be fixed by inserting some TSDoc on func(a)

interface Foo {
  /** @deprecated */
  func(a, b);
  /** fixes being marked as deprecated  */
  func(a);
}

But this trick doesn't work on functions outside of interfaces/classes

/** @deprecated */
function func(a, b);
/** new stuff */
function func(a) {}

[lloydjatkinson]

This would be greatly helpful for union types.

export type FormatName =
    | 'date-month-year-and-twelve-hour-time-with-period'
    | 'date-year-month-date'
    | 'month-name-with-day-number'
    | 'month-name-with-ordinal-date'
    /**
     * @experimental
     */
    | 'relative'
    | 'twelve-hour-time-with-period'
    | 'twelve-hour-time'
    | 'twenty-four-hour-time';