28

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?

moztemur
  • 941
  • 1
  • 9
  • 22
  • I'm going to precede the parameter description with `DEPRECATED: `. Then I'll `console.log` something if a user touches it. – yurisich Aug 05 '15 at 16:28
  • You can't deprecate parameters or properties, but you should mark the @param as optional like this `@param {string=}` – Reactgular Sep 15 '15 at 13:55
  • @Droogans of course, it is possible to inform the user about deprecated parameters in any way. I just wonder if there is a standardized way. – moztemur Sep 15 '15 at 14:03
  • @ThinkingMedia "optional" may be a way to show the user that the parameter is not mandadory, but still does not seem to match the exact meaning of "deprecated". Thanks anyway. – moztemur Sep 15 '15 at 14:07

2 Answers2

15

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

A suggestion is using typescript, like so:

function test(
  options: {
    /**
     * @deprecated use newName instead
     */
    name?: string,
    newName?: string
  }) {
}
aaron
  • 1,951
  • 3
  • 27
  • 41
  • 5
    I'm sure this was downvoted because the question is about JSDoc, but this is what I was actually looking for. It will instruct the TS compiler to mark that property as deprecated. – Payton Swick Apr 02 '21 at 21:15
  • 1
    It'll mark the property as deprecated, but the question was about marking a param. In order to follow the question, it'd need to mark the entire options object as deprecated. – Darc Sep 14 '21 at 15:51
  • @Darc, yes, and the annotation is also applicable for options too. – aaron Oct 11 '22 at 10:08