Documenting methods returning Promises

[Eric Shepherd]

This is a growing problem; we have two divergent camps that seem to have
formed around documenting functions which return Promises.

One of them does things like this:

WindowClient.navigate(url).then(function(WindowClient) {
// Do something with the returned WindowClient
});

Parameters
url
...

Returns
A Promise that resolves to the existing WindowClient.

The other does it like this:

Promise p = WindowClient.navigate(url);

Parameters
url
...

Returns
A Promise that resolves to the existing WindowClient after successfully
navigating to the specified URL.

I personally prefer the latter; this removes everything not directly
related to the method in question from the box; this is a document about
WindowClient.navigate(), not Promise.then(). It also doesn't feel as if
it excludes the option to simply do "p = WindowClient.navigate(url)" and
operate on the returned promise later.

Either way, we need to make a decision and write it down, so we can get
our docs all aligned on this. Otherwise it's a little confusing.
Inconsistency is usually not a good thing.

--

Eric Shepherd
Senior Technical Writer
Mozilla Developer Network <https://developer.mozilla.org/>
Blog: https://www.bitstampede.com/
Twitter: http://twitter.com/sheppy
Doodle: http://doodle.com/the.sheppy

[Chris Mills]

I am firmly in the other camp ;-)

I think the

Interface.method().then(function() {
//stuff
})

Is more common, and much more intuitive to see how you’d actually use the method in the wild, so better for beginners/intermediates. Advanced people can probably work the other usage model out for themselves.

I can see your point about purity, and wanting to get rid of as much cruft as possible, but I think it is a balance. Too much stripping down starts to remove useful context, making it harder to work out how to actually use it.

Chris Mills
Senior tech writer || Mozilla
developer.mozilla.org || MDN
cmi...@mozilla.com || @chrisdavidmills

> _______________________________________________
> dev-mdc mailing list
> dev...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-mdc
> MDN contributor guide: http://bit.ly/ContributorGuide
> Doc project Trello board: https://trello.com/b/HAhl54zz/status

[Jeremie Patonnier]

I'm with sheppy here :)

Even if examples should demonstrate how to use the promise, I would tend to
break it down in two steps to make things obvious that the initial method
return an object (a Promise) then how this object is used.

Doing all in one row is, IMO, misleading for beginner as it's not always
straight forward how chaining is working in JS. Using promise is more than
"then" and I think it's good to remind that manipulating promise is a whole
world in itslef just by breaking down thing in two obvious step.

--
Jeremie
.............................
Web : http://jeremie.patonnier.net
Twitter : @JeremiePat <http://twitter.com/JeremiePat>

[Chris Mills]

Showing both steps would also be ok.

Chris Mills
Senior tech writer || Mozilla
developer.mozilla.org || MDN
cmi...@mozilla.com || @chrisdavidmills

[Sebastian Zartner]

I agree with Jérémie, but I'd not only put this into two steps but
into two separate blocks. The syntax box should only contain the bare
syntax. Usage examples should be added below.

Note that in CSS we even split this into three parts. First we give
some syntax examples, after the values descriptions we show the formal
syntax and after that we list the full-featured examples. E.g. see
https://developer.mozilla.org/en-US/docs/Web/CSS/border-image.

Sebastian

[Jeremie Patonnier]

Oh yes, +1 with Sebastian

Twitter : @JeremiePat <http://twitter.com/JeremiePat>

[Eric Shepherd]

I would agree that examples should go right ahead and use the foo().then
syntax, but I definitely think the syntax box needs to simply be
Promise p = foo(). No point conflating the interface being documented
and promises themselves, IMO.

> I agree with Jérémie, but I'd not only put this into two steps but
> into two separate blocks. The syntax box should only contain the bare
> syntax. Usage examples should be added below.

[Eric Shepherd]

Agreed.

OK, any strong objections (with a good reason) for making the syntax
form below our standard?

Promise p = someObject.someMethod(<parameters>);

I do have a related thought. How closely are we trying to hew to
JavaScript syntax in the syntax box? I wonder if we would want to
consider this:

Promise<ReturnType> p = someObject.someMethod(<parameters>);

This would let the syntax box indicate what type is delivered to the
Promise's fulfillment handler; in this case, the fulfillment handler is
passed an object of type ReturnType.

This would be a way to get that information up into the syntax box. Once
I hear discussion on that idea, I'll document the results of this
discussion in our contributor guide.

jperrier wrote:
> I also think that having simply the Promise p = foo() (or similar in
> the syntax, but an example with .then() (or more) is the better of
> doing.
> (I think we should not debate the order of example/syntax now, as this
> should be done for all the properties/methods at some point)

> I would agree that examples should go right ahead and use the
> foo().then syntax, but I definitely think the syntax box needs to
> simply be Promise p = foo(). No point conflating the interface being
> documented and promises themselves, IMO.
>
>

> Sebastian Zartner <mailto:sebastia...@gmail.com>
> July 8, 2016 at 7:30 AM

> I agree with Jérémie, but I'd not only put this into two steps but
> into two separate blocks. The syntax box should only contain the bare
> syntax. Usage examples should be added below.
>

> Note that in CSS we even split this into three parts. First we give
> some syntax examples, after the values descriptions we show the formal
> syntax and after that we list the full-featured examples. E.g. see
> https://developer.mozilla.org/en-US/docs/Web/CSS/border-image.
>
> Sebastian

> Chris Mills <mailto:cmi...@mozilla.com>
> July 8, 2016 at 5:21 AM

> Showing both steps would also be ok.
>
> Chris Mills
> Senior tech writer || Mozilla
> developer.mozilla.org || MDN
> cmi...@mozilla.com || @chrisdavidmills
>
>

> Jeremie Patonnier <mailto:jeremie....@gmail.com>
> July 8, 2016 at 5:19 AM

> I'm with sheppy here :)
>
> Even if examples should demonstrate how to use the promise, I would
> tend to break it down in two steps to make things obvious that the
> initial method return an object (a Promise) then how this object is used.
>
> Doing all in one row is, IMO, misleading for beginner as it's not
> always straight forward how chaining is working in JS. Using promise
> is more than "then" and I think it's good to remind that manipulating
> promise is a whole world in itslef just by breaking down thing in two
> obvious step.
>
>
>
>

> --
> Jeremie
> .............................
> Web : http://jeremie.patonnier.net <http://jeremie.patonnier.net/>
> Twitter : @JeremiePat <http://twitter.com/JeremiePat>
> Chris Mills <mailto:cmi...@mozilla.com>
> July 8, 2016 at 4:28 AM

> I am firmly in the other camp ;-)
>
> I think the
>
> Interface.method().then(function() {
> //stuff
> })
>
> Is more common, and much more intuitive to see how you’d actually use
> the method in the wild, so better for beginners/intermediates.
> Advanced people can probably work the other usage model out for
> themselves.
>
> I can see your point about purity, and wanting to get rid of as much
> cruft as possible, but I think it is a balance. Too much stripping
> down starts to remove useful context, making it harder to work out how
> to actually use it.
>
> Chris Mills
> Senior tech writer || Mozilla
> developer.mozilla.org || MDN
> cmi...@mozilla.com || @chrisdavidmills
>
>

[Sebastian Zartner]

On 11 July 2016 at 16:06, Eric Shepherd <eshe...@mozilla.com> wrote:

> OK, any strong objections (with a good reason) for making the syntax form
> below our standard?
>
> Promise p = someObject.someMethod(<parameters>);
>
> I do have a related thought. How closely are we trying to hew to
> JavaScript syntax in the syntax box?
>

I think so far we sticked closely to the JavaScript syntax, so if we want
to keep to that, you'd have to write var p = ..., but see below.

> I wonder if we would want to consider this:
>
> Promise<ReturnType> p = someObject.someMethod(<parameters>);
>
> This would let the syntax box indicate what type is delivered to the
> Promise's fulfillment handler; in this case, the fulfillment handler is
> passed an object of type ReturnType.
>

I just read a very similar syntax (let p: Promise<ReturnType> = ...) in a
magazine today and I like that idea.
Though then we should also change other syntaxes accordingly, e.g.

Blob *blob* = *blob*.slice([start [, end [, contentType]]])

or

String *cssText* = *cssValue*.cssText

This would be a way to get that information up into the syntax box. Once I
> hear discussion on that idea, I'll document the results of this discussion
> in our contributor guide.
>

This would be an indicator for the returned type of variable additional to
the prose below allowing users to know the type at a glimpse.
Having said that, it needs to be made clear that this is a special syntax
and *not* JavaScript syntax, but I think we already agreed on having a
separate page for explaining that syntax when we discussed the square
brackets for optional parameters, right? :-)

Sebastian

>
> jperrier wrote:
>
> I also think that having simply the Promise p = foo() (or similar in the
> syntax, but an example with .then() (or more) is the better of doing.
>
> (I think we should not debate the order of example/syntax now, as this
> should be done for all the properties/methods at some point)
>
>
>
> I would agree that examples should go right ahead and use the foo().then
> syntax, but I definitely think the syntax box needs to simply be Promise p
> = foo(). No point conflating the interface being documented and promises
> themselves, IMO.
>
>

> Sebastian Zartner <sebastia...@gmail.com>

> July 8, 2016 at 7:30 AM
> I agree with Jérémie, but I'd not only put this into two steps but
> into two separate blocks. The syntax box should only contain the bare
> syntax. Usage examples should be added below.
>
> Note that in CSS we even split this into three parts. First we give
> some syntax examples, after the values descriptions we show the formal
> syntax and after that we list the full-featured examples. E.g. see
> https://developer.mozilla.org/en-US/docs/Web/CSS/border-image.
>
> Sebastian

> Chris Mills <cmi...@mozilla.com>

> July 8, 2016 at 5:21 AM
> Showing both steps would also be ok.
>
> Chris Mills
> Senior tech writer || Mozilla
> developer.mozilla.org || MDN
> cmi...@mozilla.com || @chrisdavidmills
>
>

> Jeremie Patonnier <jeremie....@gmail.com>

> July 8, 2016 at 5:19 AM
> I'm with sheppy here :)
>
> Even if examples should demonstrate how to use the promise, I would tend
> to break it down in two steps to make things obvious that the initial
> method return an object (a Promise) then how this object is used.
>
> Doing all in one row is, IMO, misleading for beginner as it's not always
> straight forward how chaining is working in JS. Using promise is more than
> "then" and I think it's good to remind that manipulating promise is a whole
> world in itslef just by breaking down thing in two obvious step.
>
>
>
>
> --
> Jeremie
> .............................
> Web : http://jeremie.patonnier.net

> Twitter : @JeremiePat <http://twitter.com/JeremiePat>
> Chris Mills <cmi...@mozilla.com>

[Joe Medley]

Forgive me for being late to the party, but I've been out for a while.

This caught my eye in one of the posts: "This would let the syntax box indicate what type is delivered to the Promise's fulfillment handler; in this case, the fulfillment handler is

passed an object of type ReturnType. "

I think any method that doesn't show the fulfillment type is doing a disservice to all developers regardless of their experience with Promises.

Also, I'm not going to let perfect be the enemy of good. The various proposals for doing this may be ugly, but I prefer them over a non-ugly solution that leaves out information.

[Eric Shepherd]

*From:* Joe Medley
*Sent:* Friday, Jul 15, 2016 3:26:22 PM EDT
*To:* mozilla...@lists.mozilla.org
*Subject:* [dev-mdc] Documenting methods returning Promises

> I think any method that doesn't show the fulfillment type is doing a disservice to all developers regardless of their experience with Promises.

I agree, actually, which is why I suggested it. That said, though, we
don't show the types of the input parameters in the syntax box; those
are listed underneath in the "Parameters" section, such as
"<dt>paramName</dt><dd>A ParamType object which indicates what
awesomesauce should happen.</dd>".

We can similarly report the return type under "Return value," such as
"Returns a Promise which resolves to an object of type ReturnType when
completed."

As a reminder to folks, this is the proposal Joe's referring to:

Promise<ReturnType> p = someObject.someMethod(<parameters>);

As mentioned in my original post about this, it's obviously not really
JS syntax, but the syntax box is about making it clear how things work;
these are never actually executable code, due to special symbols used to
indicate things like optional parameters, variable argument lists, and
so forth.

Any strong opinions on this? I personally like the idea of doing
Promise<ReturnType> foo(...) but I can see why it might be a problem for
some folks, too. It does, however, bring the type right up there where
you'll see it immediately. I can go either way, with a slight leaning
toward liking this way of having it in the syntax box itself.