Document class and type descriptions.

cpp/include/ucxx/address.h

@@ -14,6 +14,12 @@
 
 namespace ucxx {
 
+/**
+ * @brief Component encapsulating the address of a UCP worker.
+ *
+ * A UCP worker has a unique address that can is contained in a `ucp_address_t*` object,
+ * this class encapsulates that object and provides methods to simplify its handling.
+ */
 class Address : public Component {
  private:
   ucp_address_t* _handle{nullptr};

cpp/include/ucxx/buffer.h

@@ -15,12 +15,25 @@
 
 namespace ucxx {
 
+/**
+ * @brief The type of a buffer.
+ *
+ * The type of a buffer that can be used to match among the different supported types.
+ */
 enum class BufferType {
   Host = 0,
   RMM,
   Invalid,
 };
 
+/**
+ * @brief A simple object to simplify managing buffers.
+ *
+ * UCXX can work with raw pointers in most cases, but in some circumstances it's required
+ * to know more information about the buffer, such as with `ucxx::RequestTagMulti`. In such
+ * circumstances it may need to allocate buffers internally and UCXX can utilize objects of
+ * this type to describe the internally-allocated buffers.
+ */
 class Buffer {
  protected:
   BufferType _bufferType{BufferType::Invalid};  ///< Buffer type
@@ -82,6 +95,11 @@ class Buffer {
   virtual void* data() = 0;
 };
 
+/**
+ * @brief A simple object containing a host buffer.
+ *
+ * A buffer encapsulating a host buffer with its properties.
+ */
 class HostBuffer : public Buffer {
  private:
   void* _buffer;  ///< Pointer to the allocated buffer
@@ -166,6 +184,11 @@ class HostBuffer : public Buffer {
 };
 
 #if UCXX_ENABLE_RMM
+/**
+ * @brief A simple object containing a RMM (CUDA) buffer.
+ *
+ * A buffer encapsulating an RMM (CUDA) buffer with its properties.
+ */
 class RMMBuffer : public Buffer {
  private:
   std::unique_ptr<rmm::device_buffer> _buffer;  ///< RMM-allocated device buffer
@@ -245,6 +268,17 @@ class RMMBuffer : public Buffer {
 };
 #endif
 
+/**
+ * @brief Allocate a buffer of specified type and size.
+ *
+ * Allocate a buffer of the specified type and size pair, returning the `ucxx::Buffer`
+ * object wrapped in a `std::shared_ptr`.
+ *
+ * @param[in] bufferType  the type of buffer to allocate.
+ * @param[in] size        the size (in bytes) of the buffer to allocate.
+ *
+ * @returns the `std::shared_ptr` to the allocated buffer.
+ */
 std::shared_ptr<Buffer> allocateBuffer(BufferType bufferType, const size_t size);
 
 }  // namespace ucxx

cpp/include/ucxx/config.h

@@ -10,6 +10,12 @@
 
 namespace ucxx {
 
+/**
+ * @brief Component encapsulating the UCP configuration.
+ *
+ * The UCP layer provides a handle to its configuration in form of `ucp_config_t*` object,
+ * this class encapsulates that object and provides methods to simplify its handling.
+ */
 class Config {
  private:
   ucp_config_t* _handle{nullptr};  ///< Handle to the UCP config

cpp/include/ucxx/constructors.h

@@ -27,7 +27,7 @@ class RequestTagMulti;
 class Worker;
 
 // Components
-std::shared_ptr<Address> createAddressFromWorker(std::shared_ptr<ucxx::Worker> worker);
+std::shared_ptr<Address> createAddressFromWorker(std::shared_ptr<Worker> worker);
 
 std::shared_ptr<Address> createAddressFromString(std::string addressString);
 

cpp/include/ucxx/context.h

@@ -19,6 +19,12 @@ namespace ucxx {
 
 class Worker;
 
+/**
+ * @brief Component encapsulating the UCP context.
+ *
+ * The UCP layer provides a handle to access its context in form of `ucp_context_h` object,
+ * this class encapsulates that object and provides methods to simplify its handling.
+ */
 class Context : public Component {
  private:
   ucp_context_h _handle{nullptr};  ///< The UCP context handle
@@ -40,7 +46,8 @@ class Context : public Component {
 
  public:
   static constexpr uint64_t defaultFeatureFlags =
-    UCP_FEATURE_TAG | UCP_FEATURE_WAKEUP | UCP_FEATURE_STREAM | UCP_FEATURE_AM | UCP_FEATURE_RMA;
+    UCP_FEATURE_TAG | UCP_FEATURE_WAKEUP | UCP_FEATURE_STREAM | UCP_FEATURE_AM |
+    UCP_FEATURE_RMA;  ///< Suggested default context feature flags to use.
 
   Context()                          = delete;
   Context(const Context&)            = delete;

cpp/include/ucxx/delayed_submission.h

@@ -22,8 +22,20 @@
 
 namespace ucxx {
 
+/**
+ * @brief A user-defined function to execute as part of delayed submission callback.
+ *
+ * A user-defined function to execute in the scope of a `ucxx::DelayedSubmission`, allowing
+ * execution of custom code upon the completion of the delayed submission.
+ */
 typedef std::function<void()> DelayedSubmissionCallbackType;
 
+/**
+ * @brief Base type for a collection of delayed submissions.
+ *
+ * Base type for a collection of delayed submission. Delayed submissions may have different
+ * purposes and this class encapsulates generic data for all derived types.
+ */
 template <typename T>
 class BaseDelayedSubmissionCollection {
  protected:
@@ -126,6 +138,12 @@ class BaseDelayedSubmissionCollection {
   }
 };
 
+/**
+ * @brief A collection of delayed request submissions.
+ *
+ * A collection of delayed submissions used specifically for message transfer
+ * `ucxx::Request` submissions.
+ */
 class RequestDelayedSubmissionCollection
   : public BaseDelayedSubmissionCollection<
       std::pair<std::shared_ptr<Request>, DelayedSubmissionCallbackType>> {
@@ -137,9 +155,25 @@ class RequestDelayedSubmissionCollection
     std::pair<std::shared_ptr<Request>, DelayedSubmissionCallbackType> item) override;
 
  public:
+  /**
+   * @brief Constructor of a collection of delayed request submissions.
+   *
+   * Construct a collection of delayed submissions used specifically for message transfer
+   * `ucxx::Request` submissions.
+   *
+   * @param[in] name    the human-readable name of the type of delayed submission for
+   *                    debugging purposes.
+   * @param[in] enabled whether delayed request submissions should be enabled.
+   */
   explicit RequestDelayedSubmissionCollection(const std::string name, const bool enabled);
 };
 
+/**
+ * @brief A collection of delayed submissions of generic callbacks.
+ *
+ * A collection of delayed submissions used specifically for execution of generic callbacks
+ * at pre-defined stages of the progress loop.
+ */
 class GenericDelayedSubmissionCollection
   : public BaseDelayedSubmissionCollection<DelayedSubmissionCallbackType> {
  protected:
@@ -148,9 +182,24 @@ class GenericDelayedSubmissionCollection
   void processItem(DelayedSubmissionCallbackType callback) override;
 
  public:
+  /**
+   * @brief Constructor of a collection of delayed submissions of generic callbacks.
+   *
+   * Construct a collection of delayed submissions used specifically for execution of
+   * generic callbacks at pre-defined stages of the progress loop.
+   *
+   * @param[in] name    the human-readable name of the type of delayed submission for
+   *                    debugging purposes.
+   */
   explicit GenericDelayedSubmissionCollection(const std::string name);
 };
 
+/**
+ * @brief A collection of delayed submissions of multiple types.
+ *
+ * A collection of delayed submissions of multiple types used by the owner to manage each
+ * of the delayed submission types via specialized methods.
+ */
 class DelayedSubmissionCollection {
  private:
   GenericDelayedSubmissionCollection _genericPre{

cpp/include/ucxx/endpoint.h

@@ -24,10 +24,29 @@
 
 namespace ucxx {
 
+/**
+ * @brief Deleter for a endpoint parameters object.
+ *
+ * Deleter used during allocation of a `ucp_ep_params_t*` to handle automated deletion of
+ * the object when its reference count goes to zero.
+ */
 struct EpParamsDeleter {
+  /**
+   * @brief Execute the deletion.
+   *
+   * Execute the deletion of the `ucp_ep_params_t*` object.
+   *
+   * param[in] ptr  the point to the object to be deleted.
+   */
   void operator()(ucp_ep_params_t* ptr);
 };
 
+/**
+ * @brief The endpoint data that is accessible by the error callback.
+ *
+ * The `ucxx::Endpoint` data that is accessible by the asynchronous UCP endpoint error
+ * callback to modify the `ucxx::Endpoint` with information relevant to the error occurred.
+ */
 struct ErrorCallbackData {
   ucs_status_t status;                                 ///< Endpoint status
   std::shared_ptr<InflightRequests> inflightRequests;  ///< Endpoint inflight requests
@@ -36,6 +55,12 @@ struct ErrorCallbackData {
   std::shared_ptr<Worker> worker;  ///< Worker the endpoint has been created from
 };
 
+/**
+ * @brief Component encapsulating a UCP endpoint.
+ *
+ * The UCP layer provides a handle to access endpoints in form of `ucp_ep_h` object,
+ * this class encapsulates that object and provides methods to simplify its handling.
+ */
 class Endpoint : public Component {
  private:
   ucp_ep_h _handle{nullptr};          ///< Handle to the UCP endpoint
@@ -260,8 +285,6 @@ class Endpoint : public Component {
    * @param[in] closeCallback     `std::function` to a function definition return `void` and
    *                              receiving a single opaque pointer.
    * @param[in] closeCallbackArg  pointer to optional user-allocated callback argument.
-   *
-   * @returns Number of requests that were canceled.
    */
   void setCloseCallback(std::function<void(void*)> closeCallback, void* closeCallbackArg);
 

cpp/include/ucxx/future.h

@@ -12,6 +12,12 @@
 
 namespace ucxx {
 
+/**
+ * @brief Represent a future that may be notified by a specialized notifier.
+ *
+ * Represent a future object that may postpone notification of its status to a more
+ * appropriate stage by a specialize notifier, such as `ucxx::Notifier`.
+ */
 class Future : public std::enable_shared_from_this<Future> {
  protected:
   std::shared_ptr<Notifier> _notifier{nullptr};  ///< The notifier object

cpp/include/ucxx/header.h

@@ -10,8 +10,16 @@
 
 namespace ucxx {
 
-const size_t HeaderFramesSize = 100;
+const size_t HeaderFramesSize =
+  100;  ///< The number of buffers contained in a single `ucxx::Header` object.
 
+/**
+ * @brief A serializable object containing metadata of multiple buffers.
+ *
+ * A serializable object containing metadata of a pre-defined number of buffers used to
+ * inform the remote endpoint of multiple incoming messages from buffers of given
+ * properties.
+ */
 class Header {
  private:
   /**

cpp/include/ucxx/inflight_requests.h

@@ -13,20 +13,52 @@ namespace ucxx {
 
 class Request;
 
+/**
+ * @brief An inflight request map.
+ *
+ * A map of inflight requests, where keys are a unique identifier of the request and
+ * value is the reference-counted `ucxx::Request`.
+ */
 typedef std::map<const Request* const, std::shared_ptr<Request>> InflightRequestsMap;
+
+/**
+ * @brief Pre-defined type for a pointer to an inflight request map.
+ *
+ * A pre-defined type for a pointer to an inflight request map, used as a convenience type.
+ */
 typedef std::unique_ptr<InflightRequestsMap> InflightRequestsMapPtr;
+
+/**
+ * @brief A container for the different types of tracked requests.
+ *
+ * A container encapsulating the different types of handled tracked requests, currently
+ * those still valid (inflight), and those scheduled for cancelation (canceling).
+ */
 typedef struct TrackedRequests {
-  InflightRequestsMapPtr _inflight;
-  InflightRequestsMapPtr _canceling;
+  InflightRequestsMapPtr _inflight;   ///< Valid requests awaiting completion.
+  InflightRequestsMapPtr _canceling;  ///< Requests scheduled for cancelation.
 
   TrackedRequests()
     : _inflight(std::make_unique<InflightRequestsMap>()),
       _canceling(std::make_unique<InflightRequestsMap>())
   {
   }
 } TrackedRequests;
+
+/**
+ * @brief Pre-defined type for a pointer to a container of tracked requests.
+ *
+ * A pre-defined type for a pointer to a container of tracked requests, used as a
+ * convenience type.
+ */
 typedef std::unique_ptr<TrackedRequests> TrackedRequestsPtr;
 
+/**
+ * @brief Handle tracked requests.
+ *
+ * Handle tracked requests, providing functionality so that its owner can modify those
+ * requests, performing operations such as insertion, removal and cancelation.
+ */
 class InflightRequests {
  private:
   TrackedRequestsPtr _trackedRequests{

cpp/include/ucxx/internal/request_am.h

@@ -25,6 +25,12 @@ namespace internal {
 
 class AmData;
 
+/**
+ * @brief Handle receiving of a `ucxx::RequestAm`.
+ *
+ * Handle receiving of a `ucxx::RequestAm`, delivering the message to the user and
+ * notifying of completion.
+ */
 class RecvAmMessage {
  public:
   internal::AmData* _amData{nullptr};  ///< Active messages data
@@ -80,6 +86,13 @@ class RecvAmMessage {
 typedef std::unordered_map<ucp_ep_h, std::queue<std::shared_ptr<RequestAm>>> AmPoolType;
 typedef std::unordered_map<RequestAm*, std::shared_ptr<RecvAmMessage>> RecvAmMessageMapType;
 
+/**
+ * @brief Active Message data owned by a `ucxx::Worker`.
+ *
+ * Receiving Active Messages are handled directly by a `ucxx::Worker` without the user
+ * necessarily creating a `ucxx::RequestAm` for it. When there is an incoming message, the
+ * worker will populate the internal pool of received messages in an orderly-fashion.
+ */
 class AmData {
  public:
   std::weak_ptr<Worker> _worker{};  ///< The worker to which the Active Message callback belongs

cpp/include/ucxx/listener.h

@@ -14,6 +14,12 @@
 
 namespace ucxx {
 
+/**
+ * @brief Component encapsulating a UCP listener.
+ *
+ * The UCP layer provides a handle to access listeners in form of `ucp_listener_h` object,
+ * this class encapsulates that object and provides methods to simplify its handling.
+ */
 class Listener : public Component {
  private:
   ucp_listener_h _handle{nullptr};  ///< The UCP listener handle