RE: [promises] Guidance on the usage of promises for API developers

I like your way of phrasing it, because it does not explicitly queue a needless task. But I am not sure how generally it applies. What did you think of the addBookmark example?

https://github.com/domenic/promises-unwrapping/blob/master/docs/writing-specifications-with-promises.md#addbookmark--


Do you think it would be improved by nesting step 5 under "These steps will be run asynchronously"?

From: Takeshi Yoshino [mailto:tyoshino@google.com] 
Sent: Tuesday, January 14, 2014 08:30
To: www-tag@w3.org
Cc: public-webapps
Subject: Re: [promises] Guidance on the usage of promises for API developers

Nice writing! Both the shorthand phrases and guidance look very useful for writing Promise based specs.

I have only one comment on this section.
https://github.com/domenic/promises-unwrapping/blob/master/docs/writing-specifications-with-promises.md#maintain-a-normal-control-flow


I agree with your point in the first paragraph, but the suggested way looks rather confusing. The asynchronous operation abstracted by Promises is well described, but selling this convention (writing what usually happens later before return without any annotation) to everywhere sounds too much, I think. It's good to move "Return p" to the end of the steps. But how about also keeping "do blah asynchronously" text?

1. Let p be a newly-created promise.
2. These steps will be run asynchronously.
  1. If blah, reject p with undefined.
  2. If blah, resolve p with foobar.
3. Return p.

Thanks

Received on Tuesday, 14 January 2014 14:23:20 UTC