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

2014-01-29 Thread Takeshi Yoshino
New texts look nice. Two comments... - XMLHttpRequest.send() is a good example, but as we go through multiple states and invokes onreadystatechange multiple times, I prefer not just quoting "onreadystatechange" but point the one-and-done aspect of XHR by using phrase like "which triggers onreadyst

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

2014-01-29 Thread Domenic Denicola
@nokia.com] Sent: Tuesday, January 14, 2014 07:33 To: public-webapps Subject: [promises] Guidance on the usage of promises for API developers FYI. (If you want to followup, please reply on www-tag @ w3.org) Original Message Subject:Guidance on the usage of promises for

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

2014-01-17 Thread Anne van Kesteren
On Thu, Jan 16, 2014 at 7:56 PM, Boris Zbarsky wrote: > Here's an example not involving promises that's currently underspecified, I > believe: > > window1.document.createElement.call(window2.document, "span"); > > I've put the relevant testcase at > http://web.mit.edu/bzbarsky/www/testcases/mult

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

2014-01-16 Thread Tab Atkins Jr.
On Thu, Jan 16, 2014 at 10:42 AM, Anne van Kesteren wrote: > On Wed, Jan 15, 2014 at 10:26 PM, Tab Atkins Jr. wrote: >> As a voice of dissent, I *really like* the "return P, and complete the >> rest of these steps asynchronously" pattern. It's just your >> "algorithm A and B" pattern, but put in

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

2014-01-16 Thread Boris Zbarsky
On 1/16/14 1:29 PM, Domenic Denicola wrote: Hmm, I don't quite understand the concern. You're creating new objects using things like Promise.cast(). That will create an object whose prototype is Promise.prototype. But which realm's Promise is it using in this case? That needs to be specifi

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

2014-01-16 Thread Anne van Kesteren
On Wed, Jan 15, 2014 at 10:26 PM, Tab Atkins Jr. wrote: > As a voice of dissent, I *really like* the "return P, and complete the > rest of these steps asynchronously" pattern. It's just your > "algorithm A and B" pattern, but put in a single list. Having the > sync section entirely before the as

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

2014-01-16 Thread Domenic Denicola
From: Boris Zbarsky > All the terms in the "Creating Promises" are implicitly assuming operation in > a particular realm [1]. Same for the ones in "Aggregating Promises" and the > definition of "Transforming p with onFulfilled and onRejected". Same thing > for the "Promise Arguments Should B

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

2014-01-16 Thread Boris Zbarsky
On 1/14/14 7:33 AM, Arthur Barstow wrote: [2]: https://github.com/domenic/promises-unwrapping/blob/master/docs/writing-specifications-with-promises.md One issue I just realized, as I was considering how to implement some of this stuff in automated ways. All the terms in the "Creating Promises

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

2014-01-15 Thread Tab Atkins Jr.
On Tue, Jan 14, 2014 at 8:34 AM, Boris Zbarsky wrote: > On 1/14/14 10:44 AM, Domenic Denicola wrote: >> So maybe we need slightly better phrasing; help appreciated. > > Maybe the right way to spec this is to simply use two algorithms... > Algorithm A has some steps, then says to perform B asynchro

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

2014-01-15 Thread Graham Klyne
On 15/01/2014 05:23, Takeshi Yoshino wrote: Moreover, I think algorithm may be allowed to be done either synchronously or asynchronously for some cases. +1 I did some work a while ago which made extensive use of promise-like constructs (viz. Mochikit "Deferred"), and the ability to compose sy

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

2014-01-14 Thread Takeshi Yoshino
To address, jgraham's point, let's go back to just use "Run ..." style phrasing. I agree that we shouldn't mislead readers that task queuing is always necessary. Moreover, I think algorithm may be allowed to be done either synchronously or asynchronously for some cases. Maybe we could add "possibl

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

2014-01-14 Thread Boris Zbarsky
On 1/14/14 10:44 AM, Domenic Denicola wrote: So maybe we need slightly better phrasing; help appreciated. Maybe the right way to spec this is to simply use two algorithms... Algorithm A has some steps, then says to perform B asynchronously and returns a promise. B has a bunch of steps that e

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

2014-01-14 Thread Boris Zbarsky
On 1/14/14 10:44 AM, Domenic Denicola wrote: I do want to clarify that I want to avoid explicitly queuing needless tasks, which then themselves go and perform asynchronous actions. Instead, just perform the asynchronous action, and use the promise microtask queue to the deliver the results.

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

2014-01-14 Thread Domenic Denicola
From: Boris Zbarsky > On 1/14/14 9:22 AM, Domenic Denicola wrote: >> Do you think it would be improved by nesting step 5 under "These steps will >> be run asynchronously"? > > Yes. Otherwise if there is another method that allows synchronously checking > whether a bookmark has been added I wou

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

2014-01-14 Thread Boris Zbarsky
On 1/14/14 9:22 AM, Domenic Denicola wrote: Do you think it would be improved by nesting step 5 under "These steps will be run asynchronously"? Yes. Otherwise if there is another method that allows synchronously checking whether a bookmark has been added I would expect such a method to retu

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

2014-01-14 Thread Domenic Denicola
-- Do you think it would be improved by nesting step 5 under "These steps will be run asynchronously"? From: Takeshi Yoshino [mailto:tyosh...@google.com] Sent: Tuesday, January 14, 2014 08:30 To: www-...@w3.org Cc: public-webapps Subject: Re: [promises] Guidance on the usage of promis

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

2014-01-14 Thread Takeshi Yoshino
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

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

2014-01-14 Thread Arthur Barstow
FYI. (If you want to followup, please reply on www-tag @ w3.org) Original Message Subject:Guidance on the usage of promises for API developers Resent-Date:Mon, 13 Jan 2014 22:50:19 + Resent-From: Date: Mon, 13 Jan 2014 22:49:30 + From: ext Domenic Den