Add missing documentation in scalar/ headers

cpp/doxygen/Doxyfile

@@ -252,6 +252,8 @@ TAB_SIZE               = 4
 # a double escape (\\{ and \\})
 
 ALIASES                =
+ALIASES                += briefreturn{1}="@brief Returns \1 @return \1"
+ALIASES                += movedoc{1}="@brief Move Constructor for \1. @param other The other \1 to move from."
 
 # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources
 # only. Doxygen will then generate output that is more tailored for C. For

cpp/include/cudf/scalar/scalar.hpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2019-2021, NVIDIA CORPORATION.
+ * Copyright (c) 2019-2022, NVIDIA CORPORATION.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -50,7 +50,7 @@ class scalar {
   scalar& operator=(scalar&& other) = delete;
 
   /**
-   * @brief Returns the scalar's logical value type.
+   * @briefreturn{ the scalar's logical value type.}
    */
   [[nodiscard]] data_type type() const noexcept;
 
@@ -75,12 +75,12 @@ class scalar {
   [[nodiscard]] bool is_valid(rmm::cuda_stream_view stream = rmm::cuda_stream_default) const;
 
   /**
-   * @brief Returns a raw pointer to the validity bool in device memory.
+   * @briefreturn{ a raw pointer to the validity bool in device memory.}
    */
   bool* validity_data();
 
   /**
-   * @brief Returns a const raw pointer to the validity bool in device memory.
+   * @briefreturn{ a const raw pointer to the validity bool in device memory.}
    */
   [[nodiscard]] bool const* validity_data() const;
 
@@ -90,7 +90,7 @@ class scalar {
 
   scalar() = delete;
 
-  scalar(scalar&& other) = default;
+  scalar(scalar&& other) = default;  ///< @movedoc{scalar}
 
   /**
    * @brief Construct a new scalar object by deep copying another.
@@ -121,15 +121,20 @@ class scalar {
 };
 
 namespace detail {
+/**
+ * @brief An owning class to represent a fixed-width type value in device memory.
+ *
+ * @tparam T the data type of the fixed-width type value.
+ */
 template <typename T>
 class fixed_width_scalar : public scalar {
   static_assert(is_fixed_width<T>(), "Unexpected non-fixed-width type.");
 
  public:
-  using value_type = T;
+  using value_type = T;  ///< Type of the value held by the scalar.
 
   ~fixed_width_scalar() override                 = default;
-  fixed_width_scalar(fixed_width_scalar&& other) = default;
+  fixed_width_scalar(fixed_width_scalar&& other) = default;  ///< @movedoc{fixed_width_scalar}
 
   fixed_width_scalar& operator=(fixed_width_scalar const& other) = delete;
   fixed_width_scalar& operator=(fixed_width_scalar&& other) = delete;
@@ -162,16 +167,17 @@ class fixed_width_scalar : public scalar {
    * @brief Get the value of the scalar.
    *
    * @param stream CUDA stream used for device memory operations.
+   * @return Value of the scalar.
    */
   T value(rmm::cuda_stream_view stream = rmm::cuda_stream_default) const;
 
   /**
-   * @brief Returns a raw pointer to the value in device memory.
+   * @briefreturn{ a raw pointer to the value in device memory.}
    */
   T* data();
 
   /**
-   * @brief Returns a const raw pointer to the value in device memory.
+   * @briefreturn{ a const raw pointer to the value in device memory.}
    */
   T const* data() const;
 
@@ -221,7 +227,7 @@ class numeric_scalar : public detail::fixed_width_scalar<T> {
  public:
   numeric_scalar()                       = delete;
   ~numeric_scalar()                      = default;
-  numeric_scalar(numeric_scalar&& other) = default;
+  numeric_scalar(numeric_scalar&& other) = default;  ///< @movedoc{numeric_scalar}
 
   numeric_scalar& operator=(numeric_scalar const& other) = delete;
   numeric_scalar& operator=(numeric_scalar&& other) = delete;
@@ -274,12 +280,12 @@ class fixed_point_scalar : public scalar {
   static_assert(is_fixed_point<T>(), "Unexpected non-fixed_point type.");
 
  public:
-  using rep_type   = typename T::rep;
-  using value_type = T;
+  using rep_type   = typename T::rep;  ///< The representation type of the fixed_point number.
+  using value_type = T;                ///< The value type of the fixed_point number.
 
   fixed_point_scalar()                           = delete;
   ~fixed_point_scalar() override                 = default;
-  fixed_point_scalar(fixed_point_scalar&& other) = default;
+  fixed_point_scalar(fixed_point_scalar&& other) = default;  ///< @movedoc{fixed_point_scalar}
 
   fixed_point_scalar& operator=(fixed_point_scalar const& other) = delete;
   fixed_point_scalar& operator=(fixed_point_scalar&& other) = delete;
@@ -355,13 +361,15 @@ class fixed_point_scalar : public scalar {
    * @brief Get the value of the scalar.
    *
    * @param stream CUDA stream used for device memory operations.
+   * @return The value of the scalar.
    */
   rep_type value(rmm::cuda_stream_view stream = rmm::cuda_stream_default) const;
 
   /**
    * @brief Get the decimal32, decimal64 or decimal128.
    *
    * @param stream CUDA stream used for device memory operations.
+   * @return The decimal32, decimal64 or decimal128 value.
    */
   T fixed_point_value(rmm::cuda_stream_view stream = rmm::cuda_stream_default) const;
 
@@ -371,12 +379,12 @@ class fixed_point_scalar : public scalar {
   explicit operator value_type() const;
 
   /**
-   * @brief Returns a raw pointer to the value in device memory.
+   * @briefreturn{a raw pointer to the value in device memory.}
    */
   rep_type* data();
 
   /**
-   * @brief Returns a const raw pointer to the value in device memory.
+   * @briefreturn{ a const raw pointer to the value in device memory.}
    */
   rep_type const* data() const;
 
@@ -389,11 +397,11 @@ class fixed_point_scalar : public scalar {
  */
 class string_scalar : public scalar {
  public:
-  using value_type = cudf::string_view;
+  using value_type = cudf::string_view;  ///< The value type of the string scalar.
 
   string_scalar()                      = delete;
   ~string_scalar() override            = default;
-  string_scalar(string_scalar&& other) = default;
+  string_scalar(string_scalar&& other) = default;  ///< @movedoc{string_scalar}
 
   // string_scalar(string_scalar const& other) = delete;
   string_scalar& operator=(string_scalar const& other) = delete;
@@ -478,6 +486,7 @@ class string_scalar : public scalar {
    * @brief Get the value of the scalar in a host std::string.
    *
    * @param stream CUDA stream used for device memory operations.
+   * @return The value of the scalar in a host std::string.
    */
   [[nodiscard]] std::string to_string(
     rmm::cuda_stream_view stream = rmm::cuda_stream_default) const;
@@ -486,16 +495,17 @@ class string_scalar : public scalar {
    * @brief Get the value of the scalar as a string_view.
    *
    * @param stream CUDA stream used for device memory operations.
+   * @return The value of the scalar as a string_view.
    */
   [[nodiscard]] value_type value(rmm::cuda_stream_view stream = rmm::cuda_stream_default) const;
 
   /**
-   * @brief Returns the size of the string in bytes.
+   * @briefreturn{ the size of the string in bytes.}
    */
   [[nodiscard]] size_type size() const;
 
   /**
-   * @brief Returns a raw pointer to the string in device memory.
+   * @briefreturn{ a raw pointer to the string in device memory.}
    */
   [[nodiscard]] const char* data() const;
 
@@ -516,7 +526,7 @@ class chrono_scalar : public detail::fixed_width_scalar<T> {
  public:
   chrono_scalar()                      = delete;
   ~chrono_scalar()                     = default;
-  chrono_scalar(chrono_scalar&& other) = default;
+  chrono_scalar(chrono_scalar&& other) = default;  ///< @movedoc{chrono_scalar}
 
   chrono_scalar& operator=(chrono_scalar const& other) = delete;
   chrono_scalar& operator=(chrono_scalar&& other) = delete;
@@ -559,15 +569,21 @@ class chrono_scalar : public detail::fixed_width_scalar<T> {
                 rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource());
 };
 
+/**
+ * @brief An owning class to represent a timestamp value in device memory.
+ *
+ * @tparam T the data type of the timestamp value.
+ * @see cudf/wrappers/timestamps.hpp for a list of allowed types.
+ */
 template <typename T>
 class timestamp_scalar : public chrono_scalar<T> {
  public:
   static_assert(is_timestamp<T>(), "Unexpected non-timestamp type");
   using chrono_scalar<T>::chrono_scalar;
-  using rep_type = typename T::rep;
+  using rep_type = typename T::rep;  ///< The underlying representation type of the timestamp.
 
   timestamp_scalar()                         = delete;
-  timestamp_scalar(timestamp_scalar&& other) = default;
+  timestamp_scalar(timestamp_scalar&& other) = default;  ///< @movedoc{timestamp_scalar}
 
   /**
    * @brief Construct a new timestamp scalar object by deep copying another.
@@ -597,20 +613,26 @@ class timestamp_scalar : public chrono_scalar<T> {
                    rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource());
 
   /**
-   * @brief Return the duration in number of ticks since the UNIX epoch.
+   * @briefreturn{the duration in number of ticks since the UNIX epoch.}
    */
   rep_type ticks_since_epoch();
 };
 
+/**
+ * @brief An owning class to represent a duration value in device memory.
+ *
+ * @tparam T the data type of the duration value.
+ * @see cudf/wrappers/durations.hpp for a list of allowed types.
+ */
 template <typename T>
 class duration_scalar : public chrono_scalar<T> {
  public:
   static_assert(is_duration<T>(), "Unexpected non-duration type");
   using chrono_scalar<T>::chrono_scalar;
-  using rep_type = typename T::rep;
+  using rep_type = typename T::rep;  ///< The duration's underlying representation type.
 
   duration_scalar()                        = delete;
-  duration_scalar(duration_scalar&& other) = default;
+  duration_scalar(duration_scalar&& other) = default;  ///< @movedoc{duration_scalar}
 
   /**
    * @brief Construct a new duration scalar object by deep copying another.
@@ -637,7 +659,7 @@ class duration_scalar : public chrono_scalar<T> {
                   rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource());
 
   /**
-   * @brief Return the duration in number of ticks.
+   * @briefreturn{ the duration in number of ticks.}
    */
   rep_type count();
 };
@@ -649,7 +671,7 @@ class list_scalar : public scalar {
  public:
   list_scalar()                    = delete;
   ~list_scalar() override          = default;
-  list_scalar(list_scalar&& other) = default;
+  list_scalar(list_scalar&& other) = default;  ///< @movedoc{list_scalar}
 
   list_scalar& operator=(list_scalar const& other) = delete;
   list_scalar& operator=(list_scalar&& other) = delete;
@@ -694,7 +716,7 @@ class list_scalar : public scalar {
               rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource());
 
   /**
-   * @brief Returns a non-owning, immutable view to underlying device data.
+   * @briefreturn{a non-owning, immutable view to underlying device data.}
    */
   [[nodiscard]] column_view view() const;
 
@@ -709,10 +731,17 @@ class struct_scalar : public scalar {
  public:
   struct_scalar()                      = delete;
   ~struct_scalar() override            = default;
-  struct_scalar(struct_scalar&& other) = default;
+  struct_scalar(struct_scalar&& other) = default;  ///< @movedoc{struct_scalar}
   struct_scalar& operator=(struct_scalar const& other) = delete;
   struct_scalar& operator=(struct_scalar&& other) = delete;
 
+  /**
+   * @brief Construct a new struct scalar object by deep copying another.
+   *
+   * @param other The scalar to copy.
+   * @param stream CUDA stream used for device memory operations.
+   * @param mr Device memory resource to use for device memory allocation.
+   */
   struct_scalar(struct_scalar const& other,
                 rmm::cuda_stream_view stream        = rmm::cuda_stream_default,
                 rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource());
@@ -764,7 +793,7 @@ class struct_scalar : public scalar {
                 rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource());
 
   /**
-   * @brief Returns a non-owning, immutable view to underlying device data.
+   * @briefreturn{a non-owning, immutable view to underlying device data.}
    */
   [[nodiscard]] table_view view() const;