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

folly/futures/Promise.h

@@ -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;