Skip to content

Commit

Permalink
Fix doxygen warnings in fixed_point.hpp (#10922)
Browse files Browse the repository at this point in the history 
Fixes parts of #9373
added missing documentation to fix doxygen warnings in `fixed_point/fixed_point.hpp`
fixes some existing docstrings.
fixes 47 warnings.

Authors:
  - Karthikeyan (https://github.com/karthikeyann)

Approvers:
  - Vyas Ramasubramani (https://github.com/vyasr)
  - David Wendt (https://github.com/davidwendt)

URL: #10922
  • Loading branch information
@karthikeyann
karthikeyann authored Jun 1, 2022
1 parent 0e2e79d commit fae2221
Showing 1 changed file with 90 additions and 37 deletions.
127 changes: 90 additions & 37 deletions cpp/include/cudf/fixed_point/fixed_point.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,10 @@
#include <cmath>
#include <string>

//! `fixed_point` and supporting types
/// `fixed_point` and supporting types
namespace numeric {

/// The scale type for fixed_point
enum scale_type : int32_t {};

/**
Expand All @@ -46,6 +47,12 @@ enum scale_type : int32_t {};
*/
enum class Radix : int32_t { BASE_2 = 2, BASE_10 = 10 };

/**
* @brief Returns `true` if the representation type is supported by `fixed_point`
*
* @tparam T The representation type
* @return `true` if the type is supported by `fixed_point` implementation
*/
template <typename T>
constexpr inline auto is_supported_representation_type()
{
Expand All @@ -54,6 +61,12 @@ constexpr inline auto is_supported_representation_type()
cuda::std::is_same_v<T, __int128_t>;
}

/**
* @brief Returns `true` if the value type is supported for constructing a `fixed_point`
*
* @tparam T The construction value type
* @return `true` if the value type is supported to construct a `fixed_point` type
*/
template <typename T>
constexpr inline auto is_supported_construction_value_type()
{
Expand Down Expand Up @@ -175,8 +188,14 @@ CUDF_HOST_DEVICE inline constexpr T shift(T const& val, scale_type const& scale)
template <typename Rep,
typename cuda::std::enable_if_t<is_supported_representation_type<Rep>()>* = nullptr>
struct scaled_integer {
Rep value;
scale_type scale;
Rep value; ///< The value of the fixed point number
scale_type scale; ///< The scale of the value
/**
* @brief Constructor for `scaled_integer`
*
* @param v The value of the fixed point number
* @param s The scale of the value
*/
CUDF_HOST_DEVICE inline explicit scaled_integer(Rep v, scale_type s) : value{v}, scale{s} {}
};

Expand All @@ -195,7 +214,7 @@ class fixed_point {
scale_type _scale;

public:
using rep = Rep;
using rep = Rep; ///< The representation type

/**
* @brief Constructor that will perform shifting to store value appropriately (from floating point
Expand Down Expand Up @@ -244,6 +263,9 @@ class fixed_point {
/**
* @brief "Scale-less" constructor that constructs `fixed_point` number with a specified
* value and scale of zero
*
* @tparam T The value type being constructing from
* @param value The value that will be constructed from
*/
template <typename T,
typename cuda::std::enable_if_t<is_supported_construction_value_type<T>()>* = nullptr>
Expand Down Expand Up @@ -287,6 +309,11 @@ class fixed_point {
return static_cast<U>(detail::shift<Rep, Rad>(value, scale_type{-_scale}));
}

/**
* @brief Converts the `fixed_point` number to a `scaled_integer`
*
* @return The `scaled_integer` representation of the `fixed_point` number
*/
CUDF_HOST_DEVICE inline operator scaled_integer<Rep>() const
{
return scaled_integer<Rep>{_value, _scale};
Expand Down Expand Up @@ -319,8 +346,9 @@ class fixed_point {
/**
* @brief operator +=
*
* @tparam Rep1 Representation type of number being added to `this`
* @tparam Rad1 Radix (base) type of number being added to `this`
* @tparam Rep1 Representation type of the operand `rhs`
* @tparam Rad1 Radix (base) type of the operand `rhs`
* @param rhs The number being added to `this`
* @return The sum
*/
template <typename Rep1, Radix Rad1>
Expand All @@ -333,8 +361,9 @@ class fixed_point {
/**
* @brief operator *=
*
* @tparam Rep1 Representation type of number being added to `this`
* @tparam Rad1 Radix (base) type of number being added to `this`
* @tparam Rep1 Representation type of the operand `rhs`
* @tparam Rad1 Radix (base) type of the operand `rhs`
* @param rhs The number being multiplied to `this`
* @return The product
*/
template <typename Rep1, Radix Rad1>
Expand All @@ -347,8 +376,9 @@ class fixed_point {
/**
* @brief operator -=
*
* @tparam Rep1 Representation type of number being added to `this`
* @tparam Rad1 Radix (base) type of number being added to `this`
* @tparam Rep1 Representation type of the operand `rhs`
* @tparam Rad1 Radix (base) type of the operand `rhs`
* @param rhs The number being subtracted from `this`
* @return The difference
*/
template <typename Rep1, Radix Rad1>
Expand All @@ -361,8 +391,9 @@ class fixed_point {
/**
* @brief operator /=
*
* @tparam Rep1 Representation type of number being added to `this`
* @tparam Rad1 Radix (base) type of number being added to `this`
* @tparam Rep1 Representation type of the operand `rhs`
* @tparam Rad1 Radix (base) type of the operand `rhs`
* @param rhs The number being divided from `this`
* @return The quotient
*/
template <typename Rep1, Radix Rad1>
Expand Down Expand Up @@ -390,8 +421,10 @@ class fixed_point {
* If `_scale`s are not equal, the number with the larger `_scale` is shifted to the
* smaller `_scale`, and then the `_value`s are added.
*
* @tparam Rep1 Representation type of number being added to `this`
* @tparam Rad1 Radix (base) type of number being added to `this`
* @tparam Rep1 Representation type of the operand `lhs` and `rhs`
* @tparam Rad1 Radix (base) type of the operand `lhs` and `rhs`
* @param lhs The left hand side operand
* @param rhs The right hand side operand
* @return The resulting `fixed_point` sum
*/
template <typename Rep1, Radix Rad1>
Expand All @@ -405,8 +438,10 @@ class fixed_point {
* If `_scale`s are not equal, the number with the larger `_scale` is shifted to the
* smaller `_scale`, and then the `_value`s are subtracted.
*
* @tparam Rep1 Representation type of number being added to `this`
* @tparam Rad1 Radix (base) type of number being added to `this`
* @tparam Rep1 Representation type of the operand `lhs` and `rhs`
* @tparam Rad1 Radix (base) type of the operand `lhs` and `rhs`
* @param lhs The left hand side operand
* @param rhs The right hand side operand
* @return The resulting `fixed_point` difference
*/
template <typename Rep1, Radix Rad1>
Expand All @@ -418,8 +453,10 @@ class fixed_point {
*
* `_scale`s are added and `_value`s are multiplied.
*
* @tparam Rep1 Representation type of number being added to `this`
* @tparam Rad1 Radix (base) type of number being added to `this`
* @tparam Rep1 Representation type of the operand `lhs` and `rhs`
* @tparam Rad1 Radix (base) type of the operand `lhs` and `rhs`
* @param lhs The left hand side operand
* @param rhs The right hand side operand
* @return The resulting `fixed_point` product
*/
template <typename Rep1, Radix Rad1>
Expand All @@ -431,8 +468,10 @@ class fixed_point {
*
* `_scale`s are subtracted and `_value`s are divided.
*
* @tparam Rep1 Representation type of number being added to `this`
* @tparam Rad1 Radix (base) type of number being added to `this`
* @tparam Rep1 Representation type of the operand `lhs` and `rhs`
* @tparam Rad1 Radix (base) type of the operand `lhs` and `rhs`
* @param lhs The left hand side operand
* @param rhs The right hand side operand
* @return The resulting `fixed_point` quotient
*/
template <typename Rep1, Radix Rad1>
Expand All @@ -446,8 +485,10 @@ class fixed_point {
* If `_scale`s are not equal, the number with larger `_scale` is shifted to the
* smaller `_scale`, and then the modulus is computed.
*
* @tparam Rep1 Representation type of number being modulo-ed to `this`
* @tparam Rad1 Radix (base) type of number being modulo-ed to `this`
* @tparam Rep1 Representation type of the operand `lhs` and `rhs`
* @tparam Rad1 Radix (base) type of the operand `lhs` and `rhs`
* @param lhs The left hand side operand
* @param rhs The right hand side operand
* @return The resulting `fixed_point` number
*/
template <typename Rep1, Radix Rad1>
Expand All @@ -461,8 +502,10 @@ class fixed_point {
* If `_scale`s are not equal, the number with the larger `_scale` is shifted to the
* smaller `_scale`, and then the `_value`s are compared.
*
* @tparam Rep1 Representation type of number being added to `this`
* @tparam Rad1 Radix (base) type of number being added to `this`
* @tparam Rep1 Representation type of the operand `lhs` and `rhs`
* @tparam Rad1 Radix (base) type of the operand `lhs` and `rhs`
* @param lhs The left hand side operand
* @param rhs The right hand side operand
* @return true if `lhs` and `rhs` are equal, false if not
*/
template <typename Rep1, Radix Rad1>
Expand All @@ -476,8 +519,10 @@ class fixed_point {
* If `_scale`s are not equal, the number with the larger `_scale` is shifted to the
* smaller `_scale`, and then the `_value`s are compared.
*
* @tparam Rep1 Representation type of number being added to `this`
* @tparam Rad1 Radix (base) type of number being added to `this`
* @tparam Rep1 Representation type of the operand `lhs` and `rhs`
* @tparam Rad1 Radix (base) type of the operand `lhs` and `rhs`
* @param lhs The left hand side operand
* @param rhs The right hand side operand
* @return true if `lhs` and `rhs` are not equal, false if not
*/
template <typename Rep1, Radix Rad1>
Expand All @@ -491,8 +536,10 @@ class fixed_point {
* If `_scale`s are not equal, the number with the larger `_scale` is shifted to the
* smaller `_scale`, and then the `_value`s are compared.
*
* @tparam Rep1 Representation type of number being added to `this`
* @tparam Rad1 Radix (base) type of number being added to `this`
* @tparam Rep1 Representation type of the operand `lhs` and `rhs`
* @tparam Rad1 Radix (base) type of the operand `lhs` and `rhs`
* @param lhs The left hand side operand
* @param rhs The right hand side operand
* @return true if `lhs` less than or equal to `rhs`, false if not
*/
template <typename Rep1, Radix Rad1>
Expand All @@ -506,8 +553,10 @@ class fixed_point {
* If `_scale`s are not equal, the number with the larger `_scale` is shifted to the
* smaller `_scale`, and then the `_value`s are compared.
*
* @tparam Rep1 Representation type of number being added to `this`
* @tparam Rad1 Radix (base) type of number being added to `this`
* @tparam Rep1 Representation type of the operand `lhs` and `rhs`
* @tparam Rad1 Radix (base) type of the operand `lhs` and `rhs`
* @param lhs The left hand side operand
* @param rhs The right hand side operand
* @return true if `lhs` greater than or equal to `rhs`, false if not
*/
template <typename Rep1, Radix Rad1>
Expand All @@ -521,8 +570,10 @@ class fixed_point {
* If `_scale`s are not equal, the number with the larger `_scale` is shifted to the
* smaller `_scale`, and then the `_value`s are compared.
*
* @tparam Rep1 Representation type of number being added to `this`
* @tparam Rad1 Radix (base) type of number being added to `this`
* @tparam Rep1 Representation type of the operand `lhs` and `rhs`
* @tparam Rad1 Radix (base) type of the operand `lhs` and `rhs`
* @param lhs The left hand side operand
* @param rhs The right hand side operand
* @return true if `lhs` less than `rhs`, false if not
*/
template <typename Rep1, Radix Rad1>
Expand All @@ -536,8 +587,10 @@ class fixed_point {
* If `_scale`s are not equal, the number with the larger `_scale` is shifted to the
* smaller `_scale`, and then the `_value`s are compared.
*
* @tparam Rep1 Representation type of number being added to `this`
* @tparam Rad1 Radix (base) type of number being added to `this`
* @tparam Rep1 Representation type of the operand `lhs` and `rhs`
* @tparam Rad1 Radix (base) type of the operand `lhs` and `rhs`
* @param lhs The left hand side operand
* @param rhs The right hand side operand
* @return true if `lhs` greater than `rhs`, false if not
*/
template <typename Rep1, Radix Rad1>
Expand Down Expand Up @@ -774,9 +827,9 @@ CUDF_HOST_DEVICE inline fixed_point<Rep1, Rad1> operator%(fixed_point<Rep1, Rad1
return fixed_point<Rep1, Rad1>{scaled_integer<Rep1>{remainder, scale}};
}

using decimal32 = fixed_point<int32_t, Radix::BASE_10>;
using decimal64 = fixed_point<int64_t, Radix::BASE_10>;
using decimal128 = fixed_point<__int128_t, Radix::BASE_10>;
using decimal32 = fixed_point<int32_t, Radix::BASE_10>; ///< 32-bit decimal fixed point
using decimal64 = fixed_point<int64_t, Radix::BASE_10>; ///< 64-bit decimal fixed point
using decimal128 = fixed_point<__int128_t, Radix::BASE_10>; ///< 128-bit decimal fixed point

/** @} */ // end of group
} // namespace numeric

0 comments on commit fae2221

Please sign in to comment.