Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Support @deprecated for a @param #120

Open
tauren opened this Issue · 3 comments

4 participants

@tauren

The @deprecated annotation works at the class or method level, but I need to indicate that a method signature is going to change in the future.

For instance, consider where the signature was previously this:

/**
@method loadFromServer
@param urlToLoad {String} URL to load
@param callbacks {Object}  Object containing callback functions
@param callbacks.success {Function} Success callback function
@param callbacks.error {Function} Error callback function
@returns {Deferred} jQuery Deferred object
**/
loadFromServer: function(urlToLoad, callbacks) {
  return $.get(urlToLoad).done(callbacks.success).fail(callbacks.error);
}

Example usage:

loadFromServer('foo.json', {done: doneHandler, fail: failHandler});

Now, assume we want to change the API to this:

/**
@method loadFromServer
@param urlToLoad {String} URL to load
@returns {Object} jQuery Deferred object
**/
loadFromServer: function(urlToLaod) {
  return $.get(urlToLoad);
}

And the usage will change to:

loadFromServer('foo.json').done(doneHandler).fail(failHandler);

How can I indicate that the callbacks param is deprecated? Currently I'm doing this:

@param callbacks {Object} _DEPRECATED_ Object containing callback functions

I'd like to do something like one of these;

@param @deprecated callbacks {Object} Object containing callback functions
@paramDeprecated callbacks {Object} Object containing callback functions
@Arvraepe

I would like to see this happen as well!

@kalkun

This would be very welcomed

@okuryu
Collaborator

Here is a workaround for this. Please try it.

/**
 * This method is deprecated. Use `getData(name)` instead.
 *
 * @deprecated
 * @method getData
 * @param {String} name A name
 * @param {String} [option] The option object
 * @returns {Object} The data
 */

/**
 * Returns the data by a name.
 *
 * @method getData
 * @param {String} name A name
 * @returns {Object} The data
 */

This shows as follows.

2015-03-07 at 22 47

@okuryu okuryu added the enhancement label
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.