Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix doxygen warnings #1317

Merged
merged 13 commits into from
Sep 1, 2023
8 changes: 6 additions & 2 deletions doxygen/Doxyfile
Original file line number Diff line number Diff line change
Expand Up @@ -259,7 +259,11 @@ TAB_SIZE = 4
# commands \{ and \} for these it is advised to use the version @{ and @} or use
# a double escape (\\{ and \\})

ALIASES =
ALIASES += "briefreturn{1}=@brief \1 @return \1"
ALIASES += "default_copy_constructor=Default copy constructor"
ALIASES += "default_move_constructor=Default move constructor"
ALIASES += "default_copy_assignment{1}=@brief Default copy assignment operator @return \1& Reference to the assigned object"
ALIASES += "default_move_assignment{1}=@brief Default move assignment operator @return \1& Reference to the assigned object"

# 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
Expand Down Expand Up @@ -898,7 +902,7 @@ EXCLUDE_SYMLINKS = NO
# Note that the wildcards are matched against the file with absolute path, so to
# exclude all test directories for example use the pattern */test/*

EXCLUDE_PATTERNS =
EXCLUDE_PATTERNS = */detail/*

# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
# (namespaces, classes, functions, etc.) that should be excluded from the
Expand Down
10 changes: 6 additions & 4 deletions include/rmm/cuda_device.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -26,16 +26,18 @@ namespace rmm {
*
*/
struct cuda_device_id {
using value_type = int;
using value_type = int; ///< Integer type used for device identifier

/**
* @brief Construct a `cuda_device_id` from the specified integer value
* @brief Construct a `cuda_device_id` from the specified integer value.
*
* @param id The device's integer identifier
* @param dev_id The device's integer identifier
*/
explicit constexpr cuda_device_id(value_type dev_id) noexcept : id_{dev_id} {}

/// Returns the wrapped integer value
/**
* @briefreturn{The wrapped integer value.}
*/
vyasr marked this conversation as resolved.
Show resolved Hide resolved
[[nodiscard]] constexpr value_type value() const noexcept { return id_; }

private:
Expand Down
2 changes: 2 additions & 0 deletions include/rmm/cuda_stream.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,8 @@ class cuda_stream {
*
* A moved-from cuda_stream is invalid and it is Undefined Behavior to call methods that access
* the owned stream.
*
* @return A reference to this cuda_stream
*/
cuda_stream& operator=(cuda_stream&&) = default;
~cuda_stream() = default;
Expand Down
26 changes: 16 additions & 10 deletions include/rmm/cuda_stream_view.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -33,41 +33,47 @@ namespace rmm {
*/
class cuda_stream_view {
public:
constexpr cuda_stream_view() = default;
constexpr cuda_stream_view(cuda_stream_view const&) = default;
constexpr cuda_stream_view(cuda_stream_view&&) = default;
constexpr cuda_stream_view& operator=(cuda_stream_view const&) = default;
constexpr cuda_stream_view& operator=(cuda_stream_view&&) = default;
~cuda_stream_view() = default;
constexpr cuda_stream_view() = default;
~cuda_stream_view() = default;
constexpr cuda_stream_view(cuda_stream_view const&) = default; ///< @default_copy_constructor
constexpr cuda_stream_view(cuda_stream_view&&) = default; ///< @default_move_constructor
constexpr cuda_stream_view& operator=(cuda_stream_view const&) =
default; ///< @default_copy_assignment{cuda_stream_view}
constexpr cuda_stream_view& operator=(cuda_stream_view&&) =
default; ///< @default_move_assignment{cuda_stream_view}

// Disable construction from literal 0
constexpr cuda_stream_view(int) = delete; //< Prevent cast from 0
constexpr cuda_stream_view(std::nullptr_t) = delete; //< Prevent cast from nullptr

/**
* @brief Implicit conversion from cudaStream_t.
* @brief Constructor from a cudaStream_t.
*
* @param stream The underlying stream for this view.
*/
constexpr cuda_stream_view(cudaStream_t stream) noexcept : stream_{stream} {}

/**
* @brief Get the wrapped stream.
*
* @return cudaStream_t The wrapped stream.
* @return cudaStream_t The underlying stream referenced by this cuda_stream_view
*/
[[nodiscard]] constexpr cudaStream_t value() const noexcept { return stream_; }

/**
* @brief Implicit conversion to cudaStream_t.
*
* @return cudaStream_t The underlying stream referenced by this cuda_stream_view
*/
constexpr operator cudaStream_t() const noexcept { return value(); }

/**
* @brief Return true if the wrapped stream is the CUDA per-thread default stream.
* @briefreturn{true if the wrapped stream is the CUDA per-thread default stream.}
*/
[[nodiscard]] inline bool is_per_thread_default() const noexcept;

/**
* @brief Return true if the wrapped stream is explicitly the CUDA legacy default stream.
* @briefreturn{true if the wrapped stream is explicitly the CUDA legacy default stream.}
*/
[[nodiscard]] inline bool is_default() const noexcept;

Expand Down
21 changes: 13 additions & 8 deletions include/rmm/device_buffer.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,6 @@

namespace rmm {
/**
* @file device_buffer.hpp
* @brief RAII construct for device memory allocation
*
* This class allocates untyped and *uninitialized* device memory using a
Expand Down Expand Up @@ -202,6 +201,8 @@ class device_buffer {
* replaced by the `other.stream()`.
*
* @param other The `device_buffer` whose contents will be moved.
*
* @return A reference to this `device_buffer`.
*/
device_buffer& operator=(device_buffer&& other) noexcept
{
Expand Down Expand Up @@ -331,22 +332,22 @@ class device_buffer {
}

/**
* @brief Returns raw pointer to underlying device memory allocation
* @briefreturn{Const pointer to the device memory allocation}
*/
[[nodiscard]] void const* data() const noexcept { return _data; }

/**
* @brief Returns raw pointer to underlying device memory allocation
* @briefreturn{Pointer to the device memory allocation}
*/
void* data() noexcept { return _data; }

/**
* @brief Returns the number of bytes.
* @briefreturn{The number of bytes}
*/
[[nodiscard]] std::size_t size() const noexcept { return _size; }

/**
* @brief Returns the signed number of bytes.
* @briefreturn{The signed number of bytes}
*/
[[nodiscard]] std::int64_t ssize() const noexcept
{
Expand All @@ -361,18 +362,21 @@ class device_buffer {
* If `is_empty() == true`, the `device_buffer` may still hold an allocation
* if `capacity() > 0`.
*
* @return The number of bytes that can be held in currently allocated storage.
vyasr marked this conversation as resolved.
Show resolved Hide resolved
*/
[[nodiscard]] bool is_empty() const noexcept { return 0 == size(); }

/**
* @brief Returns actual size in bytes of device memory allocation.
*
* The invariant `size() <= capacity()` holds.
*
* @return The actual size in bytes of the device memory allocation
*/
[[nodiscard]] std::size_t capacity() const noexcept { return _capacity; }

/**
* @brief Returns stream most recently specified for allocation/deallocation
* @briefreturn{The stream most recently specified for allocation/deallocation}
*/
[[nodiscard]] cuda_stream_view stream() const noexcept { return _stream; }

Expand All @@ -384,12 +388,13 @@ class device_buffer {
* will be used for deallocation in the `rmm::device_uvector` destructor.
* However, if either of `resize()` or `shrink_to_fit()` is called after this,
* the later stream parameter will be stored and used in the destructor.
*
* @param stream The stream to use for deallocation
*/
void set_stream(cuda_stream_view stream) noexcept { _stream = stream; }

/**
* @brief Returns pointer to the memory resource used to allocate and
* deallocate the device memory
* @briefreturn{Pointer to the memory resource used to allocate and deallocate}
*/
[[nodiscard]] mr::device_memory_resource* memory_resource() const noexcept { return _mr; }

Expand Down
28 changes: 21 additions & 7 deletions include/rmm/device_scalar.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -37,18 +37,26 @@ class device_scalar {
public:
static_assert(std::is_trivially_copyable<T>::value, "Scalar type must be trivially copyable");

using value_type = typename device_uvector<T>::value_type;
using reference = typename device_uvector<T>::reference;
using const_reference = typename device_uvector<T>::const_reference;
using pointer = typename device_uvector<T>::pointer;
using const_pointer = typename device_uvector<T>::const_pointer;
using value_type =
typename device_uvector<T>::value_type; ///< The type of the elements in the scalar
vyasr marked this conversation as resolved.
Show resolved Hide resolved
using reference = typename device_uvector<T>::reference; ///< Not used
vyasr marked this conversation as resolved.
Show resolved Hide resolved
using const_reference = typename device_uvector<T>::const_reference; ///< Not used
vyasr marked this conversation as resolved.
Show resolved Hide resolved
vyasr marked this conversation as resolved.
Show resolved Hide resolved
using pointer =
typename device_uvector<T>::pointer; ///< The type of the pointer returned by data()
using const_pointer = typename device_uvector<T>::const_pointer; ///< The type of the iterator
///< returned by data() const

RMM_EXEC_CHECK_DISABLE
~device_scalar() = default;

RMM_EXEC_CHECK_DISABLE
device_scalar(device_scalar&&) noexcept = default;
device_scalar(device_scalar&&) noexcept = default; ///< Default move constructor

/**
* @brief Default move assignment operator
*
* @return device_scalar& A reference to the assigned-to object.
*/
device_scalar& operator=(device_scalar&&) noexcept = default;

/**
Expand Down Expand Up @@ -224,6 +232,8 @@ class device_scalar {
* specified to the constructor, then appropriate dependencies must be inserted between the
* streams (e.g. using `cudaStreamWaitEvent()` or `cudaStreamSynchronize()`), otherwise there may
* be a race condition.
*
* @return Pointer to underlying device memory
*/
[[nodiscard]] pointer data() noexcept { return static_cast<pointer>(_storage.data()); }

Expand All @@ -234,19 +244,23 @@ class device_scalar {
* specified to the constructor, then appropriate dependencies must be inserted between the
* streams (e.g. using `cudaStreamWaitEvent()` or `cudaStreamSynchronize()`), otherwise there may
* be a race condition.
*
* @return Constant pointer to underlying device memory
vyasr marked this conversation as resolved.
Show resolved Hide resolved
*/
[[nodiscard]] const_pointer data() const noexcept
{
return static_cast<const_pointer>(_storage.data());
}

/**
* @brief Returns stream most recently specified for allocation/deallocation
* @briefreturn{Stream associated with the device memory allocation}
*/
[[nodiscard]] cuda_stream_view stream() const noexcept { return _storage.stream(); }

/**
* @brief Sets the stream to be used for deallocation
*
* @param stream Stream to be used for deallocation
*/
void set_stream(cuda_stream_view stream) noexcept { _storage.set_stream(stream); }

Expand Down
39 changes: 19 additions & 20 deletions include/rmm/device_uvector.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -71,22 +71,24 @@ class device_uvector {
"device_uvector only supports types that are trivially copyable.");

public:
using value_type = T;
using size_type = std::size_t;
using reference = value_type&;
using const_reference = value_type const&;
using pointer = value_type*;
using const_pointer = value_type const*;
using iterator = pointer;
using const_iterator = const_pointer;
using value_type = T; ///< Stored value type
vyasr marked this conversation as resolved.
Show resolved Hide resolved
using size_type = std::size_t; ///< The type used for the size of the vector
wence- marked this conversation as resolved.
Show resolved Hide resolved
using reference = value_type&; ///< The type of the reference returned by operator[](size_type)
vyasr marked this conversation as resolved.
Show resolved Hide resolved
using const_reference =
value_type const&; ///< The type of the reference returned by operator[](size_type) const
vyasr marked this conversation as resolved.
Show resolved Hide resolved
using pointer = value_type*; ///< The type of the pointer returned by data()
using const_pointer = value_type const*; ///< The type of the pointer returned by data() const
using iterator = pointer; ///< The type of the ietrator returned by begin()
vyasr marked this conversation as resolved.
Show resolved Hide resolved
using const_iterator = const_pointer; ///< The type of the pointer returned by cbegin()
vyasr marked this conversation as resolved.
Show resolved Hide resolved

RMM_EXEC_CHECK_DISABLE
~device_uvector() = default;

RMM_EXEC_CHECK_DISABLE
device_uvector(device_uvector&&) noexcept = default;
device_uvector(device_uvector&&) noexcept = default; ///< @default_move_constructor

device_uvector& operator=(device_uvector&&) noexcept = default;
device_uvector& operator=(device_uvector&&) noexcept =
default; ///< @default_move_assignment{device_uvector}

/**
* @brief Copy ctor is deleted as it doesn't allow a stream argument
Expand Down Expand Up @@ -497,12 +499,12 @@ class device_uvector {
[[nodiscard]] const_iterator end() const noexcept { return cend(); }

/**
* @brief Returns the number of elements.
* @briefreturn{The number of elements in the vector.}
vyasr marked this conversation as resolved.
Show resolved Hide resolved
*/
[[nodiscard]] std::size_t size() const noexcept { return bytes_to_elements(_storage.size()); }

/**
* @brief Returns the signed number of elements.
* @briefreturn{The signed number of elements in the vector.}
*/
[[nodiscard]] std::int64_t ssize() const noexcept
{
Expand All @@ -512,25 +514,20 @@ class device_uvector {
}

/**
* @brief Returns true if the vector contains no elements, i.e., `size() == 0`.
*
* @return true The vector is empty
* @return false The vector is not empty
* @briefreturn{true if the vector is empty and false if not}
vyasr marked this conversation as resolved.
Show resolved Hide resolved
*/
[[nodiscard]] bool is_empty() const noexcept { return size() == 0; }

/**
* @brief Returns pointer to the resource used to allocate and deallocate the device storage.
*
* @return Pointer to underlying resource
* @briefreturn{Pointer to underlying resource used to allocate and deallocate the device storage}
*/
[[nodiscard]] mr::device_memory_resource* memory_resource() const noexcept
{
return _storage.memory_resource();
}

/**
* @brief Returns stream most recently specified for allocation/deallocation
* @briefreturn{Stream most recently specified for allocation/deallocation}
*/
[[nodiscard]] cuda_stream_view stream() const noexcept { return _storage.stream(); }

Expand All @@ -542,6 +539,8 @@ class device_uvector {
* will be used for deallocation in the `rmm::device_uvector destructor.
* However, if either of `resize()` or `shrink_to_fit()` is called after this,
* the later stream parameter will be stored and used in the destructor.
*
* @param stream The stream to use for deallocation
*/
void set_stream(cuda_stream_view stream) noexcept { _storage.set_stream(stream); }

Expand Down
20 changes: 17 additions & 3 deletions include/rmm/exec_policy.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,9 @@

namespace rmm {

/**
* @brief Synchronous execution policy for allocations using thrust.
*/
using thrust_exec_policy_t =
thrust::detail::execute_with_allocator<rmm::mr::thrust_allocator<char>,
thrust::cuda_cub::execute_on_stream_base>;
Expand All @@ -40,6 +43,12 @@ using thrust_exec_policy_t =
*/
class exec_policy : public thrust_exec_policy_t {
public:
/**
* @brief Construct a new exec policy object
vyasr marked this conversation as resolved.
Show resolved Hide resolved
*
* @param stream The stream on which to allocate temporary memory
* @param mr The resource to use for allocating temporary memory
*/
explicit exec_policy(cuda_stream_view stream = cuda_stream_default,
rmm::mr::device_memory_resource* mr = mr::get_current_device_resource())
: thrust_exec_policy_t(
Expand All @@ -50,6 +59,9 @@ class exec_policy : public thrust_exec_policy_t {

#if THRUST_VERSION >= 101600

/**
* @brief Asynchronous execution policy for allocations using thrust.
*/
using thrust_exec_policy_nosync_t =
thrust::detail::execute_with_allocator<rmm::mr::thrust_allocator<char>,
thrust::cuda_cub::execute_on_stream_nosync_base>;
Expand All @@ -72,9 +84,11 @@ class exec_policy_nosync : public thrust_exec_policy_nosync_t {

#else

using thrust_exec_policy_nosync_t = thrust_exec_policy_t;
using exec_policy_nosync = exec_policy;

using thrust_exec_policy_nosync_t =
thrust_exec_policy_t; ///< When used with Thrust < 1.16.0, thrust_exec_policy_nosync_t is an
///< alias for thrust_exec_policy_t
using exec_policy_nosync =
exec_policy; ///< When used with Thrust < 1.16.0, exec_policy_nosync is an alias for exec_policy
#endif

} // namespace rmm
Loading