doc(common): use real Doxygen groups

google/cloud/internal/async_retry_unary_rpc.h

@@ -55,12 +55,12 @@ template <typename RPCBackoffPolicy, typename RPCRetryPolicy,
           typename AsyncCallType, typename RequestType>
 class RetryAsyncUnaryRpc {
  public:
-  //@{
+  ///@{
   /// @name Convenience aliases for the RPC request and response types.
   using Request = RequestType;
   using Response =
       typename AsyncCallResponseType<AsyncCallType, RequestType>::type;
-  //@}
+  ///@}
 
   /**
    * Start the asynchronous retry loop.

google/cloud/internal/retry_policy.h

@@ -33,7 +33,7 @@ class RetryPolicy {
  public:
   virtual ~RetryPolicy() = default;
 
-  //@{
+  ///@{
   /**
    * @name Control retry loop duration.
    *
@@ -63,7 +63,7 @@ class RetryPolicy {
   virtual bool OnFailure(Status const&) = 0;
   virtual bool IsExhausted() const = 0;
   virtual bool IsPermanentFailure(Status const&) const = 0;
-  //@}
+  ///@}
 };
 
 /**

google/cloud/internal/sha256_hmac.h

@@ -35,7 +35,7 @@ namespace internal {
 Sha256Type Sha256Hmac(std::string const& key, absl::Span<char const> data);
 Sha256Type Sha256Hmac(std::string const& key,
                       absl::Span<std::uint8_t const> data);
-//@}
+///@}
 
 ///@{
 /**

google/cloud/internal/throw_delegate.h

@@ -25,7 +25,7 @@ namespace cloud {
 GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 namespace internal {
 
-//@{
+///@{
 /**
  * @name Delegate exception raising to out of line functions.
  *
@@ -51,7 +51,7 @@ namespace internal {
 
 [[noreturn]] void ThrowLogicError(char const* msg);
 [[noreturn]] void ThrowLogicError(std::string const& msg);
-//@}
+///@}
 
 /// Throw an exception wrapping @p status.
 [[noreturn]] void ThrowStatus(Status status);

google/cloud/internal/type_traits.h

@@ -40,7 +40,7 @@ namespace internal {
 template <typename...>
 using void_t = void;
 
-//@{
+///@{
 /**
  * A helper to detect if a type is output streamable.
  */
@@ -51,7 +51,7 @@ template <typename T>
 class IsOStreamable<
     T, void_t<decltype(std::declval<std::ostream&>() << std::declval<T>())>>
     : public std::true_type {};
-//@}
+///@}
 
 }  // namespace internal
 GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END

google/cloud/kms_key_name.h

@@ -47,12 +47,12 @@ class KmsKeyName {
              std::string const& key_ring, std::string const& kms_key_name);
 
   /// @name Copy and move
-  //@{
+  ///@{
   KmsKeyName(KmsKeyName const&) = default;
   KmsKeyName& operator=(KmsKeyName const&) = default;
   KmsKeyName(KmsKeyName&&) = default;
   KmsKeyName& operator=(KmsKeyName&&) = default;
-  //@}
+  ///@}
 
   /**
    * Returns the fully qualified KMS Key name as a string of the form:
@@ -62,13 +62,13 @@ class KmsKeyName {
   std::string const& FullName() const { return full_name_; }
 
   /// @name Equality operators
-  //@{
+  ///@{
   friend bool operator==(KmsKeyName const& a, KmsKeyName const& b);
   friend bool operator!=(KmsKeyName const& a, KmsKeyName const& b) {
     return !(a == b);
   }
-  //@}
 
+  ///@}
   /// Output the `FullName()` format.
   friend std::ostream& operator<<(std::ostream&, KmsKeyName const&);
 

google/cloud/log.h

@@ -442,17 +442,16 @@ class Logger<false> {
     if (severity_ >= Severity::GCP_LS_FATAL) std::abort();
   }
 
-  //@{
+  ///@{
   /**
-   * @name Provide trivial implementations that meet the generic `Logger<bool>`
-   * interface.
+   * @name Trivial implementations that meet the generic Logger<bool> interface.
    */
   // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
   bool enabled() const { return false; }
   void LogTo(LogSink&) {}
   // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
   NullStream Stream() { return NullStream(); }
-  //@}
+  ///@}
 
  private:
   Severity severity_;

google/cloud/polling_policy.h

@@ -99,7 +99,6 @@ class GenericPollingPolicy : public PollingPolicy {
         retry_clone_(maybe_deref(retry_prototype_).clone()),
         backoff_clone_(maybe_deref(backoff_prototype_).clone()) {}
 
-  //@{
   std::unique_ptr<PollingPolicy> clone() const override {
     return std::unique_ptr<PollingPolicy>(
         new GenericPollingPolicy<Retry, Backoff>(retry_prototype_,
@@ -113,7 +112,6 @@ class GenericPollingPolicy : public PollingPolicy {
   std::chrono::milliseconds WaitPeriod() override {
     return backoff_clone_->OnCompletion();
   }
-  //@}
 
  private:
   template <typename T>

google/cloud/project.h

@@ -43,12 +43,12 @@ class Project {
   explicit Project(std::string project_id);
 
   /// @name Copy and move
-  //@{
+  ///@{
   Project(Project const&) = default;
   Project& operator=(Project const&) = default;
   Project(Project&&) = default;
   Project& operator=(Project&&) = default;
-  //@}
+  ///@}
 
   /// Returns the Project ID
   std::string const& project_id() const { return project_id_; }
@@ -60,10 +60,10 @@ class Project {
   std::string FullName() const;
 
   /// @name Equality operators
-  //@{
+  ///@{
   friend bool operator==(Project const& a, Project const& b);
   friend bool operator!=(Project const& a, Project const& b);
-  //@}
+  ///@}
 
   /// Output the `FullName()` format.
   friend std::ostream& operator<<(std::ostream&, Project const&);

google/cloud/status_or.h

@@ -178,7 +178,7 @@ class StatusOr final {
   bool ok() const { return status_.ok(); }
   explicit operator bool() const { return status_.ok(); }
 
-  //@{
+  ///@{
   /**
    * @name Deference operators.
    *
@@ -195,9 +195,9 @@ class StatusOr final {
   T&& operator*() && { return *std::move(value_); }
 
   T const&& operator*() const&& { return *std::move(value_); }
-  //@}
+  ///@}
 
-  //@{
+  ///@{
   /**
    * @name Member access operators.
    *
@@ -210,9 +210,9 @@ class StatusOr final {
   T* operator->() & { return &*value_; }
 
   T const* operator->() const& { return &*value_; }
-  //@}
+  ///@}
 
-  //@{
+  ///@{
   /**
    * @name Value accessors.
    *
@@ -241,17 +241,17 @@ class StatusOr final {
     CheckHasValue();
     return std::move(**this);
   }
-  //@}
+  ///@}
 
-  //@{
+  ///@{
   /**
    * @name Status accessors.
    *
    * @return A reference to the contained `Status`.
    */
   Status const& status() const& { return status_; }
   Status&& status() && { return std::move(status_); }
-  //@}
+  ///@}
 
  private:
   static Status MakeDefaultStatus() {

google/cloud/stream_range.h

@@ -165,15 +165,15 @@ class StreamRange {
     reader_ = nullptr;
   }
 
-  //@{
-  // @name Move-only
+  ///@{
+  /// @name Move-only
   StreamRange(StreamRange const&) = delete;
   StreamRange& operator=(StreamRange const&) = delete;
   // NOLINTNEXTLINE(performance-noexcept-move-constructor)
   StreamRange(StreamRange&&) = default;
   // NOLINTNEXTLINE(performance-noexcept-move-constructor)
   StreamRange& operator=(StreamRange&&) = default;
-  //@}
+  ///@}
 
   iterator begin() { return iterator(this); }
   iterator end() { return iterator(); }

google/cloud/terminate_handler.h

@@ -21,22 +21,21 @@
 namespace google {
 namespace cloud {
 GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
-//@{
 /**
- * @name Control behaviour on unrecoverable errors.
+ * @defgroup terminate Control behavior on unrecoverable errors.
  *
- * The following APIs are google::cloud counterpart for
- * std::{set,get}_terminate functions. If exceptions are not enabled via
- * GOOGLE_CLOUD_CPP_HAVE_EXCEPTIONS, calling any function from throw_delegate.h
- * will result in calling the handler installed via this API. By default,
- * a call to std::abort() is used.
+ * If exceptions are not enabled via `GOOGLE_CLOUD_CPP_HAVE_EXCEPTIONS`, calling
+ * any function from throw_delegate.h will result in calling the handler
+ * installed via this API. By default, the library calls `std::abort()`.
  */
 
 /**
  * Terminate handler.
  *
  * It should handle the error, whose description are given in *msg* and should
  * never return.
+ *
+ * @ingroup terminate
  */
 using TerminateHandler = std::function<void(char const* msg)>;
 
@@ -47,13 +46,17 @@ using TerminateHandler = std::function<void(char const* msg)>;
  *        otherwise.
  *
  * @return Previously set handler.
+ *
+ * @ingroup terminate
  */
 TerminateHandler SetTerminateHandler(TerminateHandler f);
 
 /**
  * Get the currently installed handler.
  *
  * @return The currently installed handler.
+ *
+ * @ingroup terminate
  */
 TerminateHandler GetTerminateHandler();
 
@@ -63,11 +66,11 @@ TerminateHandler GetTerminateHandler();
  * @param msg Details about the error.
  *
  * This function should never return.
+ *
+ * @ingroup terminate
  */
 [[noreturn]] void Terminate(char const* msg);
 
-//@}
-
 GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
 }  // namespace cloud
 }  // namespace google