JSDoc @param together with @deprecated

Question

I have a JavaScript function getting some parameters including object types. However, one property of a parameter, which is an object, will be used as deprecated. I would like to indicate this situation in the documentation, however I don't know how to use @param tag with @deprecated. Consider the example below:

/**
* This function does something.
*
* @name myFunction
* @function
* @since 3.0
* @param {function} [onSuccess] success callback
* @param {function} [onFailure] failure callback
* @param {object} [options] options for function
* @param {string} [options.lang] display language
* @param {string} [options.type] type of sth
*/

this.myFunction= function (onSuccess, onFailure, options) {
    //do something
}

I want to deprecate "type" property of "options" object. How can I do that, or can I?

Answer 1

Official JSDoc documentation does not indicate that the @deprecated tag can be used for deprecating anything else than an entire symbol.

The @deprecated tag can be used to document that for example a function as a whole has been deprecated.

/**  * @deprecated since version 2.0.0  */ function old () {  } 

You can of course, as @Droogans said in the comments, add something like deprecated: in front of the @param description. If a developer somehow still ends up using the deprecated feature, you could implement a warning of some sorts.

/**  * @param  {string=} bar - Deprecated: description  */ function foo (bar) {   if (bar) {     console.warn('Parameter bar has been deprecated since 2.0.0')   } } 

Answer 2

A suggestion is using typescript, like so:

function test(   options: {     /**      * @deprecated use newName instead      */     name?: string,     newName?: string   }) { }