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:[email protected]] Sent: Tuesday, January 14, 2014 08:30 To: [email protected] 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
