Change the default propagateCancel argument #213
Conversation
Closes #212 Authors are more likely to expect propagation, and not cancelling is often a hidden inefficiency so it often goes unnoticed and untested. Update the doc comment to focus on the 3 ways an operation can end - as a value, an error, or a cancellation. This will hopefully make it more clear that the `onCancel` callback does not relate to the cancellation of the returned operation.
| /// Creates a new cancelable operation to be completed when this operation | ||
| /// completes normally or as an error, or is cancelled. | ||
| /// | ||
| /// If this operation completes normally the [value] is passed to [onValue] |
There was a problem hiding this comment.
@lrhn - WDYT about using the term source operation or original operation? I think returned operation is fairly clear. I intended for the consistent usage of this operation to convey the "this" that the method is called on, but I'm not sure if that comes across.
There was a problem hiding this comment.
@jakemac53 - you and I had discussed this briefly and I think you were ok with this. Should we consider making it [this] or `this`?
There was a problem hiding this comment.
I don't feel strongly, not sure what [this] would link to and I would only do that if dartdoc understand it and does something sensible, but `this` sgtm.
There was a problem hiding this comment.
It looks like Dartdoc will link [this] to the class, which is sensible but maybe not useful in this situation.
Analyzer does not have a definition to jump to, though I'd imagine if we consider it important we could make it align with dartdoc.
There was a problem hiding this comment.
I think just backticks is good then, linking the class isn't very helpful.
There was a problem hiding this comment.
I'd say no quoting at all. If you use a quoted `this`, it refers to an object and should be a noun.
In "this operation", the "this" is not a noun. (I don't know the English word for what it is, though. Preposition?)
And using "this operation" is fine with me,\
Attempt to make the distinction between "this operation" and "returned operation" stand out more.
Closes dart-lang/async#212 Authors are more likely to expect propagation, and not cancelling is often a hidden inefficiency which may go unnoticed and untested. Update the doc comment to focus on the 3 ways an operation can end - as a value, an error, or a cancellation. This will hopefully make it more clear that the `onCancel` callback does not relate to the cancellation of the returned operation.
Closes dart-lang/core#352
Authors are more likely to expect propagation, and not cancelling is
often a hidden inefficiency so it often goes unnoticed and untested.
Update the doc comment to focus on the 3 ways an operation can end - as
a value, an error, or a cancellation. This will hopefully make it more
clear that the
onCancelcallback does not relate to the cancellationof the returned operation.