Improve C++ doc comments

PiperOrigin-RevId: 688801136
Change-Id: Iaf9aca2e2d053f1c438633917ce7f640f342501a

tensorstore/array.h

@@ -2079,6 +2079,9 @@ bool IsBroadcastScalar(
 }
 
 /// Returns minimum number of contiguous bytes into which the array fits.
+///
+/// \relates Array
+/// \id array
 template <typename ElementTag, DimensionIndex Rank, ArrayOriginKind OriginKind,
           ContainerKind LayoutCKind>
 Index GetByteExtent(

tensorstore/array_storage_statistics.h

@@ -25,7 +25,11 @@
 
 namespace tensorstore {
 
+/// Response from a storage statistics query.
+///
+/// \relates GetStorageStatistics
 struct ArrayStorageStatistics {
+  /// Indicates the information to request.
   enum Mask {
     /// Query if no data is stored.
     query_not_stored = 1,
@@ -34,25 +38,22 @@ struct ArrayStorageStatistics {
     query_fully_stored = 2,
   };
 
+  /// Set operations.
   friend constexpr Mask operator~(Mask a) {
     return static_cast<Mask>(~static_cast<std::underlying_type_t<Mask>>(a));
   }
-
   friend constexpr Mask operator|(Mask a, Mask b) {
     using U = std::underlying_type_t<Mask>;
     return static_cast<Mask>(static_cast<U>(a) | static_cast<U>(b));
   }
-
   friend constexpr Mask& operator|=(Mask& a, Mask b) {
     using U = std::underlying_type_t<Mask>;
     return a = static_cast<Mask>(static_cast<U>(a) | static_cast<U>(b));
   }
-
   friend constexpr Mask operator&(Mask a, Mask b) {
     using U = std::underlying_type_t<Mask>;
     return static_cast<Mask>(static_cast<U>(a) & static_cast<U>(b));
   }
-
   friend constexpr Mask operator&=(Mask& a, Mask b) {
     using U = std::underlying_type_t<Mask>;
     return a = static_cast<Mask>(static_cast<U>(a) & static_cast<U>(b));
@@ -88,6 +89,7 @@ struct ArrayStorageStatistics {
     return !(a == b);
   }
 
+  /// Prints a debug representation.
   friend std::ostream& operator<<(std::ostream& os,
                                   const ArrayStorageStatistics& a);
 
@@ -96,6 +98,14 @@ struct ArrayStorageStatistics {
   };
 };
 
+/// Specifies options for computing array storage statistics.
+///
+/// Supported option types are:
+///
+///   - `Batch`
+///   - `ArrayStorageStatistics::Mask`
+///
+/// \relates GetStorageStatistics
 struct GetArrayStorageStatisticsOptions {
   ArrayStorageStatistics::Mask mask = {};
 

tensorstore/batch.h

@@ -29,6 +29,8 @@ namespace tensorstore {
 ///
 /// For some operations, there are batch implementations there are batch
 /// implementations that reduce the number of separate I/O requests performed.
+///
+/// \ingroup core
 class Batch {
   class ImplBase {
    public:
@@ -55,10 +57,14 @@ class Batch {
   class View {
    public:
     /// Constructs a view that refers to `no_batch`.
+    ///
+    /// \id no_batch
     constexpr View() = default;
     constexpr View(no_batch_t) {}
 
     /// Constructs a view that refers to an existing batch.
+    ///
+    /// \id batch
     constexpr View(const Batch& batch) : impl_(batch.impl_.get()) {}
 
     /// Returns `true` if this refers to a batch (as opposed to `no_batch`).
@@ -113,6 +119,9 @@ class Batch {
   internal::IntrusivePtr<ImplBase> impl_;
 };
 
+/// Alias for indicating not to use a batch.
+///
+/// \relates Batch
 constexpr inline Batch::no_batch_t no_batch = Batch::no_batch_t{};
 
 }  // namespace tensorstore

tensorstore/box.h

@@ -96,7 +96,7 @@ constexpr inline bool IsMutableBoxLike =
 /// type with `Box::static_rank` implicitly convertible to `Rank`.
 ///
 /// \relates Box
-template <typename T, DimensionIndex Rank, typename = void>
+template <typename T, DimensionIndex Rank, typename Sfinae = void>
 constexpr inline bool IsBoxLikeImplicitlyConvertibleToRank = false;
 
 template <typename T, DimensionIndex Rank>
@@ -108,7 +108,7 @@ constexpr inline bool IsBoxLikeImplicitlyConvertibleToRank<
 /// type with `Box::static_rank` explicitly convertible to `Rank`.
 ///
 /// \relates Box
-template <typename T, DimensionIndex Rank, typename = void>
+template <typename T, DimensionIndex Rank, typename Sfinae = void>
 constexpr inline bool IsBoxLikeExplicitlyConvertibleToRank = false;
 
 template <typename T, DimensionIndex Rank>
@@ -439,8 +439,8 @@ Box(const Index (&shape)[Rank]) -> Box<Rank>;
 template <typename Origin, typename Shape,
           std::enable_if_t<(IsIndexConvertibleVector<Origin> &&
                             IsIndexConvertibleVector<Shape>)>* = nullptr>
-Box(const Origin& origin, const Shape& shape)
-    -> Box<SpanStaticExtent<Origin, Shape>::value>;
+Box(const Origin& origin,
+    const Shape& shape) -> Box<SpanStaticExtent<Origin, Shape>::value>;
 
 template <DimensionIndex Rank>
 Box(const Index (&origin)[Rank], const Index (&shape)[Rank]) -> Box<Rank>;
@@ -557,12 +557,11 @@ class BoxView : public internal_box::BoxViewStorage<Rank, Mutable> {
   /// \requires If `Mutable == true`, `BoxType` must be a mutable Box-like type
   ///     (such as a non-const `Box` reference or a `MutableBoxView`).
   /// \id convert
-  template <
-      typename BoxType,
-      typename = std::enable_if_t<
-          (IsBoxLike<BoxType> &&
-           (!Mutable || IsMutableBoxLike<BoxType>)&&RankConstraint::Implies(
-               absl::remove_cvref_t<BoxType>::static_rank, Rank))>>
+  template <typename BoxType,
+            typename = std::enable_if_t<(
+                IsBoxLike<BoxType> && (!Mutable || IsMutableBoxLike<BoxType>) &&
+                RankConstraint::Implies(
+                    absl::remove_cvref_t<BoxType>::static_rank, Rank))>>
   // NONITPICK: std::remove_cvref_t<BoxType>::static_rank
   BoxView(BoxType&& other)
       : BoxView(other.rank(), other.origin().data(), other.shape().data()) {}
@@ -587,7 +586,7 @@ class BoxView : public internal_box::BoxViewStorage<Rank, Mutable> {
       typename BoxType,
       std::enable_if_t<
           (IsBoxLike<absl::remove_cvref_t<BoxType>> &&
-           (!Mutable || IsMutableBoxLike<std::remove_reference_t<BoxType>>)&&
+           (!Mutable || IsMutableBoxLike<std::remove_reference_t<BoxType>>) &&
 
            RankConstraint::Implies(absl::remove_cvref_t<BoxType>::static_rank,
                                    Rank))>* = nullptr>
@@ -704,8 +703,8 @@ BoxView(Origin&& origin, Shape&& shape)
                (IsMutableIndexVector<Origin> && IsMutableIndexVector<Shape>)>;
 
 template <DimensionIndex Rank>
-BoxView(const Index (&origin)[Rank], const Index (&shape)[Rank])
-    -> BoxView<Rank>;
+BoxView(const Index (&origin)[Rank],
+        const Index (&shape)[Rank]) -> BoxView<Rank>;
 
 template <DimensionIndex Rank, bool Mutable>
 struct StaticCastTraits<BoxView<Rank, Mutable>>
@@ -897,10 +896,12 @@ std::enable_if_t<HasBoxDomain<BoxType>, bool> ContainsPartial(
 /// Returns a view of the sub-box corresponding to the specified dimension
 /// range.
 ///
-/// \params box The existing box from which to extract the sub-box.
-/// \param  begin Inclusive start dimension of the sub-box.
-/// \param end Exclusive end dimension of the sub-box.  The default value of
-///     `-1` is treated the same as `box.rank()`.
+/// \param box The existing box from which to extract the sub-box.
+/// \param begin Inclusive start dimension of the sub-box.
+/// \param end Exclusive end dimension of the sub-box.
+///     The default value of ``-1`` is treated the same as `box.rank()`.
+///
+/// \relates Box
 template <typename BoxType>
 std::enable_if_t<IsBoxLike<BoxType>,
                  BoxView<dynamic_rank, IsMutableBoxLike<BoxType>>>

tensorstore/cast.h

@@ -61,6 +61,7 @@ namespace tensorstore {
 /// \error `absl::StatusCode::kInvalidArgument` if neither reading nor writing
 ///     would be supported by the returned `TensorStore`.
 /// \relates TensorStore
+/// \id TensorStore
 template <typename TargetElementType, int&... ExplicitArgumentBarrier,
           typename ElementType, DimensionIndex Rank, ReadWriteMode Mode>
 Result<TensorStore<
@@ -100,6 +101,7 @@ Cast(TensorStore<ElementType, Rank, Mode> store, DataType target_dtype) {
 /// \error `absl::StatusCode::kInvalidArgument` if the conversion is not
 ///     supported.
 /// \relates Spec
+/// \id Spec
 Result<Spec> Cast(const Spec& base_spec, DataType target_dtype);
 
 }  // namespace tensorstore

tensorstore/data_type.h

@@ -466,6 +466,8 @@ inline constexpr DataTypeConversionFlags operator&(DataTypeConversionFlags a,
 }
 
 /// Specifies an equality comparison method.
+///
+/// \relates DataType
 enum class EqualityComparisonKind {
   /// Compare using regular equality (``operator==``).  For floating point
   /// types, this considers positive and negative zero equal, and NaN unequal to
@@ -476,7 +478,7 @@ enum class EqualityComparisonKind {
   ///
   /// For integer and floating point types, this performs a bitwise comparison.
   ///
-  /// For integer types this is equivalent to `kCompareEqual`.
+  /// For integer types this is equivalent to `equal`.
   identical,
 };
 
@@ -1551,6 +1553,7 @@ constexpr DataType kDataTypes[] = {
 ///
 /// \relates ElementPointer
 template <typename Pointer>
+// NONITPICK: std::pointer_traits<std::remove_cvref_t<Pointer>>::element_type
 using pointee_dtype_t = dtype_t<
     typename std::pointer_traits<absl::remove_cvref_t<Pointer>>::element_type>;