Feature/add promise doc

[jannyHou]

Connect to #1998

[jannyHou]

hey @bajtos take your time to review it :)
I add @promise doc for each function in #1998

Some questions:

1. If a method only has error message in callback, sdocs --preview will give warning like

Resolve object not found in User.confirm()

But doc page looks fine:
Handler | Argument | Description
resolve | undefined | The resolve handler does not receive any arguments.

2. promise annotation cannot read Array with datatype like Change [] from callback, so in PersistedModel.replicate
   I am thinking of overwriting the description derived from callback, eg:

@promise {Conflict[]} conflicts A list of changes that could not be replicated due to conflicts.
{Object] checkpoints The new checkpoints to use as the "since" argument for the next replication.

[bajtos]

1. If a method only has error message in callback, sdocs --preview will give warning like

Resolve object not found in User.confirm()

But doc page looks fine:
Handler | Argument | Description
resolve | undefined | The resolve handler does not receive any arguments.

@hacksparrow could you PTAL?

[bajtos]

2. promise annotation cannot read Array with datatype like Change [] from callback, so in PersistedModel.replicate
   I am thinking of overwriting the description derived from callback, eg:

@promise {Conflict[]} conflicts A list of changes that could not be replicated due to conflicts.
{Object] checkpoints The new checkpoints to use as the "since" argument for the next replication.

According to jsdoc, {Conflict[]} is a valid syntax.

OTOH, Google Closure Compiler uses {Array<Conflict>} to describe typed array.

@hacksparrow do you happen to know why "promise annotation cannot read Array with datatype like Change[] from callback"? Is this something that can be fixed in strong-docs?

[bajtos]

@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]

@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]

Fair enough.

[bajtos]

@jannyHou the changes look good to me so far. Please let me know when this is no longer "work in progress".

[jannyHou]

@bajtos Thanks for reviewing so quickly, and sorry I put work in progress when I created it but forgot to delete them :) it's done now excepts the problem I mentioned above.
I will wait for Yaapa's reply, I guess he's also quite busy these days.

[bajtos]

@jannyHou LGTM. Please rebase on top of the current master and squash the commits before landing.