search

w3ctag / promises-guide

A guide for spec authors on how to use Promises in prose and WebIDL.
https://www.w3.org/2001/tag/doc/promises-guide
192 stars 24 forks source link

"Transforming with/by a fulfilment handler" is confusing #40

Closed jan-ivar closed 9 years ago

jan-ivar commented 9 years ago

The term Transforming p with a fulfillment and/or rejection handler sounds like it modifies p:

var p = someAsyncOperation();
var p2 = p.catch(() => {}); // has no effect on p

One might not often care about p at this point, in which case the wording seems forgiveable, but in https://github.com/w3c/webrtc-pc/pull/222, p critically is used later, and I had to make this point in prose to not confuse people. The term is also not very descriptive of the action happening.

Instead, how about:

_Let_ p2 _be the result of appending to_ p _a fulfillment and/or rejection handler that runs the following steps:_

?

jan-ivar commented 9 years ago

Another word might be "chaining" if we don't like "appending".

jan-ivar commented 9 years ago

@domenic thoughts?

domenic commented 9 years ago

I think this breaks existing consumers, who are already using this phrasing, for no real benefit. "The result of transforming x" doesn't imply that x changes. Similar to "the result of translating x with a computer translation program" or similar phrases.

alvestrand commented 9 years ago

Just a +1 to the point that "transforming X" sounds like "X will change".

http://dictionary.reference.com/browse/transform has about 10 meanings, only one of which (mathematical transform) doesn't imply a change to the souce object.

jan-ivar commented 9 years ago

Translating and transforming are different words. Use it in a sentence.

alvestrand commented 9 years ago

Just to be clear - I have no particular beef with recommending the use of the word "transform" in this way. But when there is an unusual usage of a word in my document, I want either a definition of the word in my document or a normative reference to the document that defines that usage.

In this case, I would need a normative dependency from webrtc-pc to promises-guide. And that requires the status of promises-guide to be clear.

domenic commented 9 years ago

I changed the status to "Finding of the TAG"; hope that helps.

jan-ivar commented 9 years ago

What about the with/by inconsistency? Is it engrained?

domenic commented 9 years ago

What inconsistency?

jan-ivar commented 9 years ago

'with' is used in the prose, and 'by' is used in the example. Which one is recommended and why are there two?

domenic commented 9 years ago

Good call, will fix that up. I'll do a survey of users to make sure to align before deciding between them.

domenic commented 9 years ago

Sorry for taking so long on this. I settled on "with".