Skip to content

Feature/add promise doc #2040

New issue

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

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jannyHou merged 1 commit into from
Apr 4, 2016
Merged

Feature/add promise doc #2040

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions common/models/application.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,9 @@ module.exports = function(Application) {
* @param {String} owner Owner's user ID.
* @param {String} name Name of the application
* @param {Object} options Other options
* @param {Function} callback Callback function
* @callback {Function} callback Callback function
* @param {Error} err

@bajtos bajtos Feb 9, 2016

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@hacksparrow Is it necessary to add @param {Error} err to callbacks that have at most one argument? I.e. cb(err) on error, cb() on success.

I would prefer if strong-docs was able to add this automatically.

@hacksparrow hacksparrow Feb 29, 2016

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@bajtos In my opinion, we should make it explicit. Reasons:

  1. Helps to give more details about the error, if required.
  2. When a human being looks at the source code, if the error param is missing, it will be interpreted as the callback returns nothing. Only sdocs will be able to add the missing info. We should avoid magic.

@bajtos bajtos Feb 29, 2016

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair enough.

* @promise
*/
Application.register = function(owner, name, options, cb) {
assert(owner, 'owner is required');
Expand Down Expand Up @@ -150,6 +152,7 @@ module.exports = function(Application) {
* @param {Any} appId
* @callback {Function} callback
* @param {Error} err
* @promise
*/
Application.resetKeys = function(appId, cb) {
cb = cb || utils.createPromiseCallback();
Expand All @@ -176,7 +179,7 @@ module.exports = function(Application) {
* - restApiKey
* - windowsKey
* - masterKey
*
* @promise
*/
Application.authenticate = function(appId, key, cb) {
cb = cb || utils.createPromiseCallback();
Expand Down
10 changes: 10 additions & 0 deletions common/models/user.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,7 @@ module.exports = function(User) {
* @callback {Function} cb The callback function
* @param {String|Error} err The error string or object
* @param {AccessToken} token The generated access token object
* @promise
*/
User.prototype.createAccessToken = function(ttl, options, cb) {
if (cb === undefined && typeof options === 'function') {
Expand Down Expand Up @@ -169,6 +170,7 @@ module.exports = function(User) {
* @callback {Function} callback Callback function
* @param {Error} err Error object
* @param {AccessToken} token Access token if login is successful
* @promise
*/

User.login = function(credentials, include, fn) {
Expand Down Expand Up @@ -281,6 +283,7 @@ module.exports = function(User) {
* @param {String} accessTokenID
* @callback {Function} callback
* @param {Error} err
* @promise
*/

User.logout = function(tokenId, fn) {
Expand All @@ -304,6 +307,7 @@ module.exports = function(User) {
* @callback {Function} callback Callback function
* @param {Error} err Error object
* @param {Boolean} isMatch Returns true if the given `password` matches record
* @promise
*/

User.prototype.hasPassword = function(plain, fn) {
Expand Down Expand Up @@ -350,6 +354,10 @@ module.exports = function(User) {
* callback function. This function should NOT add the token to the user
* object, instead simply execute the callback with the token! User saving
* and email sending will be handled in the `verify()` method.
* @callback {Function} fn Callback function.
* @param {Error} err Error object.
* @param {Object} object Contains email, token, uid.
* @promise
*/

User.prototype.verify = function(options, fn) {
Expand Down Expand Up @@ -463,6 +471,7 @@ module.exports = function(User) {
* @param {String} redirect URL to redirect the user to once confirmed
* @callback {Function} callback
* @param {Error} err
* @promise
*/
User.confirm = function(uid, token, redirect, fn) {
fn = fn || utils.createPromiseCallback();
Expand Down Expand Up @@ -505,6 +514,7 @@ module.exports = function(User) {
* @prop {String} email The user's email address
* @callback {Function} callback
* @param {Error} err
* @promise
*/

User.resetPassword = function(options, cb) {
Expand Down
4 changes: 3 additions & 1 deletion lib/persisted-model.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -925,8 +925,10 @@ module.exports = function(registry) {
* @callback {Function} [callback] Callback function called with `(err, conflicts)` arguments.
* @param {Error} err Error object; see [Error object](http://docs.strongloop.com/display/LB/Error+object).
* @param {Conflict[]} conflicts A list of changes that could not be replicated due to conflicts.
* @param {Object] checkpoints The new checkpoints to use as the "since"
* @param {Object} checkpoints The new checkpoints to use as the "since"
* argument for the next replication.
*
* @promise
*/

PersistedModel.replicate = function(since, targetModel, options, callback) {
Expand Down