Commit d539094f authored by Marshall Cline's avatar Marshall Cline Committed by Facebook Github Bot

Fix doc-comment inconsistencies in class Promise

Summary:
Non-functional comment-only changes.

Goal: Adjust Promise's code-docs so they are consistent with Future and SemiFuture, e.g., change "valid() must be true" to "`valid() == true`"

Reviewed By: LeeHowes

Differential Revision: D9415137

fbshipit-source-id: dbb8df00919779b339e5b08337eba0df1a210ac2
parent 25c2411f
......@@ -145,24 +145,24 @@ class Promise {
///
/// Postconditions:
///
/// RESULT.valid() will be false
/// RESULT.isFulfilled() will be true
/// - `RESULT.valid() == false`
/// - `RESULT.isFulfilled() == true`
static Promise<T> makeEmpty() noexcept;
/// Constructs a valid but unfulfilled promise.
///
/// Postconditions:
///
/// - valid() will be true (it will have a shared state)
/// - isFulfilled() will be false (its shared state won't have a result)
/// - `valid() == true` (it will have a shared state)
/// - `isFulfilled() == false` (its shared state won't have a result)
Promise();
/// Postconditions:
///
/// - If valid() and !isFulfilled(), the associated future (if any) will be
/// completed with a `BrokenPromise` exception *as if* by
/// - If `valid()` and `!isFulfilled()`, the associated future (if any) will
/// be completed with a `BrokenPromise` exception *as if* by
/// `setException(...)`.
/// - If valid(), releases, possibly destroying, the shared state.
/// - If `valid()`, releases, possibly destroying, the shared state.
~Promise();
// not copyable
......@@ -182,10 +182,10 @@ class Promise {
///
/// Postconditions:
///
/// - If valid() and !isFulfilled(), the associated future (if any) will be
/// completed with a `BrokenPromise` exception *as if* by
/// - If `valid()` and `!isFulfilled()`, the associated future (if any) will
/// be completed with a `BrokenPromise` exception *as if* by
/// `setException(...)`.
/// - If valid(), releases, possibly destroying, the original shared state.
/// - If `valid()`, releases, possibly destroying, the original shared state.
/// - `this` will have whatever shared-state was previously held by `other`
/// (if any)
/// - `other.valid()` will be false (`other` will not have any shared state)
......@@ -196,13 +196,13 @@ class Promise {
///
/// Preconditions:
///
/// - valid() (else throws PromiseInvalid)
/// - `valid() == true` (else throws PromiseInvalid)
/// - neither getSemiFuture() nor getFuture() may have been called previously
/// on `this` Promise (else throws FutureAlreadyRetrieved)
///
/// Postconditions:
///
/// - RESULT.valid() will be true
/// - `RESULT.valid() == true`
/// - RESULT will share the same shared-state as `this`
///
/// DEPRECATED: use `folly::makePromiseContract()` instead.
......@@ -213,13 +213,13 @@ class Promise {
///
/// Preconditions:
///
/// - valid() (else throws PromiseInvalid)
/// - `valid() == true` (else throws PromiseInvalid)
/// - neither getSemiFuture() nor getFuture() may have been called previously
/// on `this` Promise (else throws FutureAlreadyRetrieved)
///
/// Postconditions:
///
/// - RESULT.valid() will be true
/// - `RESULT.valid() == true`
/// - RESULT will share the same shared-state as `this`
///
/// DEPRECATED: use `folly::makePromiseContract()` instead. If you can't use
......@@ -241,13 +241,13 @@ class Promise {
///
/// Preconditions:
///
/// - valid() (else throws PromiseInvalid)
/// - !isFulfilled() (else throws PromiseAlreadySatisfied)
/// - `valid() == true` (else throws PromiseInvalid)
/// - `isFulfilled() == false` (else throws PromiseAlreadySatisfied)
///
/// Postconditions:
///
/// - isFulfilled() will be true
/// - valid() will be unchanged (true)
/// - `isFulfilled() == true`
/// - `valid() == true` (unchanged)
/// - The associated future (if any) will complete with the exception.
void setException(exception_wrapper ew);
......@@ -276,7 +276,7 @@ class Promise {
///
/// Preconditions:
///
/// - valid() (else throws PromiseInvalid)
/// - `valid() == true` (else throws PromiseInvalid)
/// - `fn` must be copyable and must be invocable with
/// `exception_wrapper const&`
/// - the code within `fn()` must be safe to run either synchronously within
......@@ -314,13 +314,13 @@ class Promise {
///
/// Preconditions:
///
/// - valid() (else throws PromiseInvalid)
/// - !isFulfilled() (else throws PromiseAlreadySatisfied)
/// - `valid() == true` (else throws PromiseInvalid)
/// - `isFulfilled() == false` (else throws PromiseAlreadySatisfied)
///
/// Postconditions:
///
/// - isFulfilled() will be true
/// - valid() will be unchanged (true)
/// - `isFulfilled() == true`
/// - `valid() == true` (unchanged)
template <class B = T>
typename std::enable_if<std::is_same<Unit, B>::value, void>::type
setValue() {
......@@ -333,13 +333,13 @@ class Promise {
///
/// Preconditions:
///
/// - valid() (else throws PromiseInvalid)
/// - !isFulfilled() (else throws PromiseAlreadySatisfied)
/// - `valid() == true` (else throws PromiseInvalid)
/// - `isFulfilled() == false` (else throws PromiseAlreadySatisfied)
///
/// Postconditions:
///
/// - isFulfilled() will be true
/// - valid() will be unchanged (true)
/// - `isFulfilled() == true`
/// - `valid() == true` (unchanged)
/// - The associated future will see the value, e.g., in its continuation.
template <class M>
void setValue(M&& value);
......@@ -348,13 +348,13 @@ class Promise {
///
/// Preconditions:
///
/// - valid() (else throws PromiseInvalid)
/// - !isFulfilled() (else throws PromiseAlreadySatisfied)
/// - `valid() == true` (else throws PromiseInvalid)
/// - `isFulfilled() == false` (else throws PromiseAlreadySatisfied)
///
/// Postconditions:
///
/// - isFulfilled() will be true
/// - valid() will be unchanged (true)
/// - `isFulfilled() == true`
/// - `valid() == true` (unchanged)
/// - The associated future will see the result, e.g., in its continuation.
void setTry(Try<T>&& t);
......@@ -369,8 +369,8 @@ class Promise {
///
/// Preconditions:
///
/// - valid() (else throws PromiseInvalid)
/// - !isFulfilled() (else throws PromiseAlreadySatisfied)
/// - `valid() == true` (else throws PromiseInvalid)
/// - `isFulfilled() == false` (else throws PromiseAlreadySatisfied)
///
/// Postconditions:
///
......@@ -379,8 +379,8 @@ class Promise {
/// `setValue()`
/// - If `func()` throws, the exception will be captured as if via
/// `setException()`
/// - isFulfilled() will be true
/// - valid() will be unchanged (true)
/// - `isFulfilled() == true`
/// - `valid() == true` (unchanged)
/// - The associated future will see the result, e.g., in its continuation.
template <class F>
void setWith(F&& func);
......@@ -393,8 +393,8 @@ class Promise {
/// True if either this promise was fulfilled or is invalid.
///
/// - True if !valid()
/// - True if valid() and this was fulfilled (a prior call to `setValue()`,
/// - True if `!valid()`
/// - True if `valid()` and this was fulfilled (a prior call to `setValue()`,
/// `setTry()`, `setException()`, or `setWith()`)
bool isFulfilled() const noexcept;
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment