Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

Inconsistencies regarding callbacks in JSDoc #294

Open
jakub-g opened this Issue Dec 18, 2012 · 0 comments

Comments

Projects
None yet
1 participant
Collaborator

jakub-g commented Dec 18, 2012

  1. Currently, we use the following values in @param section of JSDoc to indicate that a param is a callback:
aria.core.JsObject.Callback
aria.utils.Callback
aria.core.CfgBeans.Callback

In majority (or all) of the cases, the last one should be used.

  1. The entry aria.core.CfgBeans.Callback should be updated to reflect all the possible ways to define callbacks:

Here are some examples of valid callbacks:

  • an instance of aria.utils.Callback
  • the name of a method as a string: "myMethod"
  • the reference to a function: myMethod
  • an object with fn, scope, args and apply properties. fn can be either a function reference or a method name (as a string) to be looked for in the scope: {fn:"myMethod", scope: myScope}, {fn: myScope.myMethod, scope: myScope}
    It is possible to omit the scope, and then a default scope is used (the object on which the $callback method is called)
  1. However, in some places in code, like here, internally we do not use $callback which makes some of the forms not valid for some of the methods. We should double check that and either change the code, or make sure that docs say it clearly which are the valid types of callbacks.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment