JSDoc @param along with @deprecated

Question

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

/** * 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 invalidate the type property of an options object. How can I do this, or can I?

Answer 1

The official JSDoc documentation does not mean that the @deprecated tag can be used to discard anything other than a whole character.

The @deprecated tag can be used to document that, for example, the function as a whole is deprecated.

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

You can, of course, as @Droogans said in the comments, add something like deprecated: before the description of @param . If the developer somehow still ends up using the deprecated function, you can implement a warning about any roles.

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