Skip to content

Commit

Permalink
Fix Doxygen warnings in table header files (#10964)
Browse files Browse the repository at this point in the history 
Fixes parts of #9373
added missing documentation to fix doxygen warnings in table headers
ignores doc generation for `strong_index_comparator_adapter`

fixes 166  warnings.

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

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

URL: #10964
  • Loading branch information
@karthikeyann
karthikeyann authored Jun 2, 2022
1 parent 75f667e commit c01a2a4
Show file tree
Hide file tree
Showing 5 changed files with 396 additions and 41 deletions.
117 changes: 97 additions & 20 deletions cpp/include/cudf/table/experimental/row_operators.cuh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,7 @@ namespace experimental {
*/
template <cudf::type_id t>
struct dispatch_void_if_nested {
/// The type to dispatch to if the type is nested
using type = std::conditional_t<cudf::is_nested(data_type(t)), void, id_to_type<t>>;
};

Expand Down Expand Up @@ -95,11 +96,17 @@ struct strong_index_iterator : public thrust::iterator_facade<strong_index_itera
thrust::random_access_traversal_tag,
Index,
Underlying> {
using super_t = thrust::iterator_adaptor<strong_index_iterator<Index>, Index>;
using super_t =
thrust::iterator_adaptor<strong_index_iterator<Index>, Index>; ///< The base class

/**
* @brief Constructs a strong index iterator
*
* @param n The beginning index
*/
explicit constexpr strong_index_iterator(Underlying n) : begin{n} {}

friend class thrust::iterator_core_access;
friend class thrust::iterator_core_access; ///< Allow access to the base class

private:
__device__ constexpr void increment() { ++begin; }
Expand Down Expand Up @@ -154,8 +161,8 @@ namespace lexicographic {
*/
template <typename Nullate>
class device_row_comparator {
friend class self_comparator;
friend class two_table_comparator;
friend class self_comparator; ///< Allow self_comparator to access private members
friend class two_table_comparator; ///< Allow two_table_comparator to access private members

/**
* @brief Construct a function object for performing a lexicographic
Expand Down Expand Up @@ -378,7 +385,12 @@ template <typename Comparator>
using less_equivalent_comparator =
weak_ordering_comparator_impl<Comparator, weak_ordering::LESS, weak_ordering::EQUIVALENT>;

/**
* @brief Preprocessed table for use with lexicographical comparison
*
*/
struct preprocessed_table {
/// Type of table device view owner for the preprocessed table.
using table_device_view_owner =
std::invoke_result_t<decltype(table_device_view::create), table_view, rmm::cuda_stream_view>;

Expand All @@ -396,15 +408,16 @@ struct preprocessed_table {
* values compare to all other for every column. If it is nullptr, then null precedence would be
* `null_order::BEFORE` for all columns.
* @param stream The stream to launch kernels and h->d copies on while preprocessing.
* @return A shared pointer to a preprocessed table
*/
static std::shared_ptr<preprocessed_table> create(table_view const& table,
host_span<order const> column_order,
host_span<null_order const> null_precedence,
rmm::cuda_stream_view stream);

private:
friend class self_comparator;
friend class two_table_comparator;
friend class self_comparator; ///< Allow self_comparator to access private members
friend class two_table_comparator; ///< Allow two_table_comparator to access private members

preprocessed_table(table_device_view_owner&& table,
rmm::device_uvector<order>&& column_order,
Expand Down Expand Up @@ -525,6 +538,8 @@ class self_comparator {
* `F(i,j)` returns true if and only if row `i` compares lexicographically less than row `j`.
*
* @tparam Nullate A cudf::nullate type describing whether to check for nulls.
* @param nullate Indicates if either input column contains nulls
* @return A binary callable object
*/
template <typename Nullate>
less_comparator<device_row_comparator<Nullate>> device_comparator(Nullate nullate = {}) const
Expand All @@ -537,6 +552,7 @@ class self_comparator {
std::shared_ptr<preprocessed_table> d_t;
};

// @cond
template <typename Comparator>
struct strong_index_comparator_adapter {
__device__ constexpr weak_ordering operator()(lhs_index_type const lhs_index,
Expand All @@ -563,6 +579,7 @@ struct strong_index_comparator_adapter {

Comparator const comparator;
};
// @endcond

/**
* @brief An owning object that can be used to lexicographically compare rows of two different
Expand Down Expand Up @@ -636,6 +653,8 @@ class two_table_comparator {
* `j` of the left table.
*
* @tparam Nullate A cudf::nullate type describing whether to check for nulls.
* @param nullate Indicates if either input column contains nulls.
* @return A binary callable object
*/
template <typename Nullate>
less_comparator<strong_index_comparator_adapter<device_row_comparator<Nullate>>>
Expand All @@ -662,11 +681,15 @@ class row_hasher;
}

namespace equality {

/**
* @brief Comparator for performing equality comparison between the rows of two tables.
*
* @tparam Nullate A cudf::nullate type describing whether to check for nulls.
*/
template <typename Nullate>
class device_row_comparator {
friend class self_comparator;
friend class two_table_comparator;
friend class self_comparator; ///< Allow self_comparator to access private members
friend class two_table_comparator; ///< Allow two_table_comparator to access private members

public:
/**
Expand Down Expand Up @@ -860,24 +883,30 @@ class device_row_comparator {
null_equality const nulls_are_equal;
};

/**
* @brief Preprocessed table for use with row equality comparison or row hashing
*
*/
struct preprocessed_table {
/**
* @brief Preprocess table for use with row equality comparison or row hashing
* @brief Factory to construct preprocessed_table for use with
* row equality comparison or row hashing
*
* Sets up the table for use with row equality comparison or row hashing. The resulting
* preprocessed table can be passed to the constructor of `equality::self_comparator` to
* avoid preprocessing again.
*
* @param table The table to preprocess
* @param stream The cuda stream to use while preprocessing.
* @return A preprocessed table as shared pointer
*/
static std::shared_ptr<preprocessed_table> create(table_view const& table,
rmm::cuda_stream_view stream);

private:
friend class self_comparator;
friend class two_table_comparator;
friend class hash::row_hasher;
friend class self_comparator; ///< Allow self_comparator to access private members
friend class two_table_comparator; ///< Allow two_table_comparator to access private members
friend class hash::row_hasher; ///< Allow row_hasher to access private members

using table_device_view_owner =
std::invoke_result_t<decltype(table_device_view::create), table_view, rmm::cuda_stream_view>;
Expand All @@ -899,6 +928,10 @@ struct preprocessed_table {
std::vector<rmm::device_buffer> _null_buffers;
};

/**
* @brief Comparator for performing equality comparisons between two rows of the same table.
*
*/
class self_comparator {
public:
/**
Expand Down Expand Up @@ -932,7 +965,10 @@ class self_comparator {
*
* `F(i,j)` returns true if and only if row `i` compares equal to row `j`.
*
* @tparam Nullate A cudf::nullate type describing whether to check for nulls.
* @tparam Nullate A cudf::nullate type describing whether to check for nulls
* @param nullate Indicates if either input column contains nulls
* @param nulls_are_equal Indicates if nulls are equal
* @return A binary callable object
*/
template <typename Nullate>
device_row_comparator<Nullate> device_comparator(
Expand All @@ -945,6 +981,7 @@ class self_comparator {
std::shared_ptr<preprocessed_table> d_t;
};

// @cond
template <typename Comparator>
struct strong_index_comparator_adapter {
__device__ constexpr bool operator()(lhs_index_type const lhs_index,
Expand All @@ -962,6 +999,7 @@ struct strong_index_comparator_adapter {

Comparator const comparator;
};
// @endcond

/**
* @brief An owning object that can be used to equality compare rows of two different tables.
Expand Down Expand Up @@ -1022,7 +1060,10 @@ class two_table_comparator {
* Similarly, `F(rhs_index_type i, lhs_index_type j)` returns true if and only if row `i` of the
* right table compares equal to row `j` of the left table.
*
* @tparam Nullate A cudf::nullate type describing whether to check for nulls.
* @tparam Nullate A cudf::nullate type describing whether to check for nulls
* @param nullate Indicates if either input column contains nulls
* @param nulls_are_equal Indicates if nulls are equal
* @return A binary callable object
*/
template <typename Nullate>
auto device_comparator(Nullate nullate = {},
Expand Down Expand Up @@ -1050,6 +1091,13 @@ namespace hash {
template <template <typename> class hash_function, typename Nullate>
class element_hasher {
public:
/**
* @brief Constructs an element_hasher object.
*
* @param nulls Indicates whether to check for nulls
* @param seed The seed to use for the hash function
* @param null_hash The hash value to use for nulls
*/
__device__ element_hasher(
Nullate nulls,
uint32_t seed = DEFAULT_HASH_SEED,
Expand All @@ -1058,6 +1106,14 @@ class element_hasher {
{
}

/**
* @brief Returns the hash value of the given element.
*
* @tparam T The type of the element to hash
* @param col The column to hash
* @param row_index The index of the row to hash
* @return The hash value of the given element
*/
template <typename T, CUDF_ENABLE_IF(column_device_view::has_element_accessor<T>())>
__device__ hash_value_type operator()(column_device_view const& col,
size_type row_index) const noexcept
Expand All @@ -1066,16 +1122,24 @@ class element_hasher {
return hash_function<T>{_seed}(col.element<T>(row_index));
}

/**
* @brief Returns the hash value of the given element.
*
* @tparam T The type of the element to hash
* @param col The column to hash
* @param row_index The index of the row to hash
* @return The hash value of the given element
*/
template <typename T, CUDF_ENABLE_IF(not column_device_view::has_element_accessor<T>())>
__device__ hash_value_type operator()(column_device_view const& col,
size_type row_index) const noexcept
{
CUDF_UNREACHABLE("Unsupported type in hash.");
}

uint32_t _seed;
hash_value_type _null_hash;
Nullate _check_nulls;
uint32_t _seed; ///< The seed to use for hashing
hash_value_type _null_hash; ///< Hash value to use for null elements
Nullate _check_nulls; ///< Whether to check for nulls
};

/**
Expand All @@ -1086,11 +1150,17 @@ class element_hasher {
*/
template <template <typename> class hash_function, typename Nullate>
class device_row_hasher {
friend class row_hasher;
friend class row_hasher; ///< Allow row_hasher to access private members.

public:
device_row_hasher() = delete;

/**
* @brief Return the hash value of a row in the given table.
*
* @param row_index The row index to compute the hash value of
* @return The hash value of the row
*/
__device__ auto operator()(size_type row_index) const noexcept
{
auto it = thrust::make_transform_iterator(_table.begin(), [=](auto const& column) {
Expand Down Expand Up @@ -1187,6 +1257,10 @@ class device_row_hasher {
// type and are interchangeable.
using preprocessed_table = row::equality::preprocessed_table;

/**
* @brief Computes the hash value of a row in the given table.
*
*/
class row_hasher {
public:
/**
Expand Down Expand Up @@ -1219,7 +1293,10 @@ class row_hasher {
*
* `F(i)` returns the hash of row i.
*
* @tparam Nullate A cudf::nullate type describing whether to check for nulls.
* @tparam Nullate A cudf::nullate type describing whether to check for nulls
* @param nullate Indicates if either input column contains nulls
* @param seed The seed to use for the hash function
* @return A hash operator to use on the device
*/
template <template <typename> class hash_function = detail::default_hash, typename Nullate>
device_row_hasher<hash_function, Nullate> device_hasher(Nullate nullate = {},
Expand Down
Loading

0 comments on commit c01a2a4

Please sign in to comment.