docs(common): better exception descriptions (#11705)

googleapis · May 23, 2023 · 96f2b47 · 96f2b47
1 parent 64aae9e
commit 96f2b47
Show file tree

Hide file tree

Showing 4 changed files with 15 additions and 5 deletions.
diff --git a/google/cloud/future_generic.h b/google/cloud/future_generic.h
@@ -77,7 +77,7 @@ class future final : private internal::future_base<T> {
    * @note This operation invalidates the future, subsequent calls will fail,
    *   the application should capture the returned value because it would.
    *
-   * @throws any exceptions stored in the shared state.
+   * @throws ... any exceptions stored in the shared state.
    * @throws std::future_error with std::no_state if the future does not have
    *   a shared state.
    */

diff --git a/google/cloud/future_void.h b/google/cloud/future_void.h
@@ -71,7 +71,7 @@ class future<void> final : private internal::future_base<void> {
    * Waits until the shared state becomes ready, then retrieves the value stored
    * in the shared state.
    *
-   * @throws any exceptions stored in the shared state.
+   * @throws ... any exceptions stored in the shared state.
    * @throws std::future_error with std::no_state if the future does not have
    *   a shared state.
    */

diff --git a/google/cloud/internal/future_impl.h b/google/cloud/internal/future_impl.h
@@ -372,7 +372,7 @@ class future_shared_state final : public future_shared_state_base {
    * stores the value and the state becomes satisfied.
    *
    * @param value the value to store in the shared state.
-   * @throws `std::future_error` if the shared state was already satisfied. The
+   * @throws std::future_error if the shared state was already satisfied. The
    *     error code is `std::future_errc::promise_already_satisfied`.
    */
   void set_value(T value) {

diff --git a/google/cloud/status_or.h b/google/cloud/status_or.h
@@ -176,11 +176,21 @@ class StatusOr final {
    *
    * @param rhs the value used to initialize the object.
    *
-   * @throws only if `T`'s move constructor throws.
+   * @throws ... If `T`'s move constructor throws.
    */
   // NOLINTNEXTLINE(google-explicit-constructor)
   StatusOr(T&& rhs) : value_(std::move(rhs)) {}
 
+  /**
+   * Creates a new `StatusOr<T>` holding the value @p rhs.
+   *
+   * @par Post-conditions
+   * `ok() == true` and `value() == rhs`.
+   *
+   * @param rhs the value used to initialize the object.
+   *
+   * @throws ... If `T` copy constructor throws.
+   */
   // NOLINTNEXTLINE(google-explicit-constructor)
   StatusOr(T const& rhs) : value_(rhs) {}
 
@@ -240,7 +250,7 @@ class StatusOr final {
    * @return All these member functions return a (properly ref and
    *     const-qualified) reference to the underlying value.
    *
-   * @throws `RuntimeStatusError` with the contents of `status()` if the object
+   * @throws RuntimeStatusError with the contents of `status()` if the object
    *   does not contain a value, i.e., if `ok() == false`.
    */
   T& value() & {