Tsdoc: How to deprecate a single parameter

[JoshuaKGoldberg]

https://github.com/palantir/tslint/issues/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.