CODEWITHSUNDEEP
javascriptdeprecatedjsdocparam
moztemur
moztemur

Reputation: 971

JSDoc @param together with @deprecated

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?

Upvotes: 30

Views: 20785

Answers (2)

user1878974
user1878974

Reputation:

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')
  }
}

Upvotes: 14

aaron
aaron

Reputation: 2046

A suggestion is using typescript, like so:

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

Upvotes: 12

Related Questions