📝 Add docstrings to ystade/qdmi-sc-device

Docstrings generation was requested by @ystade.

* #1328 (comment)

The following files were modified:

* `include/mqt-core/qdmi/sc/Device.hpp`
* `src/na/device/Device.cpp`
* `src/qdmi/Driver.cpp`
* `src/qdmi/sc/App.cpp`
* `src/qdmi/sc/Device.cpp`
* `src/qdmi/sc/DynDevice.cpp`
* `src/qdmi/sc/Generator.cpp`
* `test/na/device/test_app.cpp`
* `test/na/device/test_device.cpp`
* `test/na/device/test_generator.cpp`
* `test/qdmi/sc/test_app.cpp`
* `test/qdmi/sc/test_device.cpp`
* `test/qdmi/sc/test_generator.cpp`
* `test/qdmi/test_driver.cpp`

Author: coderabbitai[bot]

include/mqt-core/qdmi/sc/Device.hpp

@@ -47,14 +47,38 @@ class Device final {
   Device();
 
 public:
-  // Default move constructor and move assignment operator.
+  /**
+ * @brief Move-constructs a Device, transferring ownership of internal resources.
+ *
+ * Leaves the moved-from instance in a valid but unspecified state.
+ */
   Device(Device&&) = default;
-  Device& operator=(Device&&) = default;
-  // Delete copy constructor and assignment operator to enforce singleton.
+  /**
+ * @brief Move-assigns the Device instance from another Device.
+ *
+ * @param other rvalue reference to the source Device to move from.
+ * @return Device& Reference to this Device after move assignment.
+ */
+Device& operator=(Device&&) = default;
+  /**
+ * @brief Deleted copy constructor to prevent copying of the singleton Device.
+ *
+ * Deleting this constructor enforces the singleton pattern by disallowing copy construction.
+ */
   Device(const Device&) = delete;
-  Device& operator=(const Device&) = delete;
+  /**
+ * @brief Deleted copy assignment operator to prevent copying of the Device singleton.
+ *
+ * The Device class is non-copyable; assigning from another Device is disallowed to
+ * preserve the singleton semantics and unique device state.
+ */
+Device& operator=(const Device&) = delete;
 
-  /// @returns the singleton instance of the Device class.
+  /**
+   * @brief Accesses the singleton Device instance.
+   *
+   * @return Device& Reference to the singleton Device instance.
+   */
   [[nodiscard]] static Device& get() {
     static Device instance;
     return instance;
@@ -162,7 +186,11 @@ struct MQT_SC_QDMI_Device_Job_impl_d {
   MQT_SC_QDMI_Device_Session_impl_d* session_;
 
 public:
-  /// @brief Constructor for the MQT_SC_QDMI_Device_Job_impl_d.
+  /**
+       * @brief Initializes a device job implementation bound to the given session.
+       *
+       * @param session Pointer to the owning MQT_SC_QDMI_Device_Session_impl_d. The session must remain valid for the job's lifetime.
+       */
   explicit MQT_SC_QDMI_Device_Job_impl_d(
       MQT_SC_QDMI_Device_Session_impl_d* session)
       : session_(session) {}
@@ -231,7 +259,11 @@ struct MQT_SC_QDMI_Site_impl_d {
 private:
   uint64_t id_ = 0; ///< Unique identifier of the site
 
-  /// @brief Constructor for regular sites.
+  /**
+ * @brief Initializes a site implementation with the given unique identifier.
+ *
+ * @param id Unique identifier for the site.
+ */
   MQT_SC_QDMI_Site_impl_d(uint64_t id) : id_(id) {}
 
 public:
@@ -267,4 +299,4 @@ struct MQT_SC_QDMI_Operation_impl_d {
                      size_t numParams, const double* params,
                      QDMI_Operation_Property prop, size_t size, void* value,
                      size_t* sizeRet) const -> int;
-};
+};

src/na/device/Device.cpp

@@ -90,6 +90,12 @@
 // NOLINTEND(bugprone-macro-parentheses)
 
 namespace qdmi::na {
+/**
+ * @brief Constructs the device and initializes its metadata and supported entities.
+ *
+ * Initializes the device name, number of qubits, minimum atom distance, length and
+ * duration units/scale factors, and populates the site and operation lists.
+ */
 Device::Device() {
   // NOLINTBEGIN(cppcoreguidelines-prefer-member-initializer)
   INITIALIZE_NAME(name_);
@@ -120,6 +126,26 @@ auto Device::sessionFree(MQT_NA_QDMI_Device_Session session) -> void {
     }
   }
 }
+/**
+ * @brief Retrieve a device-level property value.
+ *
+ * Query a named device property and copy its value into the provided buffer
+ * (or report the required size). Supported properties include metadata
+ * (name, version), numeric characteristics (qubit count, minimum atom
+ * distance, units/scale factors), lists (sites, operations), and device
+ * capabilities.
+ *
+ * @param prop The device property being queried.
+ * @param size Size of the buffer pointed to by `value` in bytes; may be 0
+ *             when `value` is nullptr to request the required size.
+ * @param value Pointer to a buffer to receive the property value, or nullptr
+ *              to only retrieve the required size.
+ * @param sizeRet If non-null, receives the number of bytes written or the
+ *                number of bytes required.
+ * @return int `QDMI_SUCCESS` on success; `QDMI_ERROR_INVALIDARGUMENT` if
+ *         arguments are invalid; `QDMI_ERROR_NOTSUPPORTED` if the property
+ *         is not recognized or not supported.
+ */
 auto Device::queryProperty(const QDMI_Device_Property prop, const size_t size,
                            void* value, size_t* sizeRet) -> int {
   if ((value != nullptr && size == 0) || prop >= QDMI_DEVICE_PROPERTY_MAX) {
@@ -161,7 +187,13 @@ auto Device::queryProperty(const QDMI_Device_Property prop, const size_t size,
                     operations_, prop, size, value, sizeRet)
   return QDMI_ERROR_NOTSUPPORTED;
 }
-} // namespace qdmi::na
+} /**
+ * @brief Initialize the device session by transitioning it from ALLOCATED to INITIALIZED.
+ *
+ * Sets the session's internal state to INITIALIZED when it is currently ALLOCATED.
+ *
+ * @return int `QDMI_SUCCESS` on successful initialization, `QDMI_ERROR_BADSTATE` if the session was not in the ALLOCATED state.
+ */
 
 auto MQT_NA_QDMI_Device_Session_impl_d::init() -> int {
   if (status_ != Status::ALLOCATED) {
@@ -201,6 +233,15 @@ auto MQT_NA_QDMI_Device_Session_impl_d::freeDeviceJob(
     jobs_.erase(job);
   }
 }
+/**
+ * @brief Query a device-level property for this session.
+ *
+ * @param prop The device property to query.
+ * @param size Size of the caller-provided buffer pointed to by `value`, in bytes.
+ * @param value Pointer to a buffer to receive the property's value; may be null to query required size.
+ * @param sizeRet Pointer to receive the number of bytes written or required; may be null if not needed.
+ * @return int QDMI status code: `QDMI_SUCCESS` on success, `QDMI_ERROR_BADSTATE` if the session is not initialized, `QDMI_ERROR_NOTSUPPORTED` if the property is not supported, or other QDMI error codes on failure.
+ */
 auto MQT_NA_QDMI_Device_Session_impl_d::queryDeviceProperty(
     const QDMI_Device_Property prop, const size_t size, void* value,
     size_t* sizeRet) const -> int {
@@ -209,6 +250,20 @@ auto MQT_NA_QDMI_Device_Session_impl_d::queryDeviceProperty(
   }
   return qdmi::na::Device::get().queryProperty(prop, size, value, sizeRet);
 }
+/**
+ * @brief Query a property of the specified site within this session.
+ *
+ * Validates the session state and the site handle before performing the query.
+ *
+ * @param site Site handle to query; must not be `nullptr`.
+ * @param prop Property to query.
+ * @param size Size of the buffer pointed to by `value`, in bytes.
+ * @param value Output buffer for the property value; may be `nullptr` to obtain required size.
+ * @param sizeRet Receives the number of bytes written or required; may be `nullptr` if not needed.
+ * @return int `QDMI_ERROR_INVALIDARGUMENT` if `site` is `nullptr`.
+ * `QDMI_ERROR_BADSTATE` if the session is not initialized.
+ * Otherwise, returns the status code produced while retrieving the site's property. 
+ */
 auto MQT_NA_QDMI_Device_Session_impl_d::querySiteProperty(
     MQT_NA_QDMI_Site site, const QDMI_Site_Property prop, const size_t size,
     void* value, size_t* sizeRet) const -> int {
@@ -542,7 +597,27 @@ auto MQT_NA_QDMI_Operation_impl_d::queryProperty(
                               *duration_, prop, size, value, sizeRet)
   }
   if (fidelity_) {
-    ADD_SINGLE_VALUE_PROPERTY(QDMI_OPERATION_PROPERTY_FIDELITY, double,
+    /**
+ * @brief Query an operation property for the specified sites and parameters.
+ *
+ * Validates the provided site pointers and parameter pointers, checks that the
+ * supplied sites are compatible with this operation (including ordering for
+ * two-qubit operations), and writes the requested property into the provided
+ * buffer if supported.
+ *
+ * @param numSites Number of sites in `sites`.
+ * @param sites Pointer to an array of site handles to query against.
+ * @param numParams Number of numeric parameters in `params`.
+ * @param params Pointer to an array of parameter values (may be nullptr if none).
+ * @param prop The operation property to query.
+ * @param size Size of the `value` buffer in bytes.
+ * @param value Buffer to receive the property value (may be nullptr to query required size).
+ * @param sizeRet If non-null, receives the number of bytes written or required.
+ * @return int `QDMI_ERROR_SUCCESS` if the property was written to `value`;
+ * `QDMI_ERROR_NOTSUPPORTED` if the property or the supplied site/parameter
+ * combination is not supported; `QDMI_ERROR_BADARG` for invalid input arguments.
+ */
+ADD_SINGLE_VALUE_PROPERTY(QDMI_OPERATION_PROPERTY_FIDELITY, double,
                               *fidelity_, prop, size, value, sizeRet)
   }
   if (numQubits_) {
@@ -558,28 +633,69 @@ auto MQT_NA_QDMI_Operation_impl_d::queryProperty(
   return QDMI_ERROR_NOTSUPPORTED;
 }
 
+/**
+ * @brief Initializes the NA QDMI device subsystem by ensuring the Device singleton exists.
+ *
+ * @return QDMI_SUCCESS on success.
+ */
 int MQT_NA_QDMI_device_initialize() {
   std::ignore = qdmi::na::Device::get(); // Ensure the singleton is created
   return QDMI_SUCCESS;
 }
 
+/**
+ * @brief Finalizes the NA QDMI device subsystem and releases any global resources.
+ *
+ * Performs any final cleanup required by the device subsystem prior to library unload.
+ *
+ * @return int `QDMI_SUCCESS` on success.
+ */
 int MQT_NA_QDMI_device_finalize() { return QDMI_SUCCESS; }
 
+/**
+ * @brief Allocates a new device session and returns its handle.
+ *
+ * @param session Pointer to storage that receives the new MQT_NA_QDMI_Device_Session handle; must not be null.
+ * @return int Status code indicating success or failure. On success the out-parameter `session` is set to the allocated session handle.
+ */
 int MQT_NA_QDMI_device_session_alloc(MQT_NA_QDMI_Device_Session* session) {
   return qdmi::na::Device::get().sessionAlloc(session);
 }
 
+/**
+ * @brief Initializes a device session.
+ *
+ * @param session Pointer to an allocated device session handle.
+ * @return int QDMI_SUCCESS on success; QDMI_ERROR_INVALIDARGUMENT if `session` is null; otherwise the status code returned by the session initialization.
+ */
 int MQT_NA_QDMI_device_session_init(MQT_NA_QDMI_Device_Session session) {
   if (session == nullptr) {
     return QDMI_ERROR_INVALIDARGUMENT;
   }
   return session->init();
 }
 
+/**
+ * @brief Release a device session handle and free its internal resources.
+ *
+ * If `session` is non-null and corresponds to an allocated session, the session
+ * is removed and its resources are freed; passing a null handle has no effect.
+ *
+ * @param session Session handle to free.
+ */
 void MQT_NA_QDMI_device_session_free(MQT_NA_QDMI_Device_Session session) {
   qdmi::na::Device::get().sessionFree(session);
 }
 
+/**
+ * @brief Set a parameter for a device session.
+ *
+ * @param session Handle to an allocated device session.
+ * @param param Identifier of the session parameter to set.
+ * @param size Size in bytes of the data pointed to by `value`.
+ * @param value Pointer to the parameter data.
+ * @return int QDMI status code: `QDMI_ERROR_INVALIDARGUMENT` if `session` is null; otherwise the status returned by the session implementation.
+ */
 int MQT_NA_QDMI_device_session_set_parameter(
     MQT_NA_QDMI_Device_Session session, QDMI_Device_Session_Parameter param,
     const size_t size, const void* value) {
@@ -723,4 +839,4 @@ int MQT_NA_QDMI_device_session_query_operation_property(
   }
   return session->queryOperationProperty(operation, numSites, sites, numParams,
                                          params, prop, size, value, sizeRet);
-}
+}

src/qdmi/Driver.cpp

@@ -80,6 +80,18 @@ DEFINE_STATIC_LIBRARY(MQT_DDSIM)
 DEFINE_STATIC_LIBRARY(MQT_SC)
 
 #ifndef _WIN32
+/**
+ * @brief Load a device shared library, bind required QDMI symbols using the given prefix, and initialize the device.
+ *
+ * Opens the shared library specified by libName, resolves the set of required QDMI symbols named using
+ * the pattern "<prefix>_QDMI_<symbol>", and calls the library's initialize function.
+ *
+ * @param libName Path or filename of the shared library to load.
+ * @param prefix Symbol name prefix used to construct exported QDMI symbol names (e.g., prefix_QDMI_device_initialize).
+ *
+ * @throws std::runtime_error If the library cannot be opened, if the library is already loaded,
+ *         or if any required symbol cannot be resolved.
+ */
 DynamicDeviceLibrary::DynamicDeviceLibrary(const std::string& libName,
                                            const std::string& prefix)
     : libHandle_(dlopen(libName.c_str(), RTLD_NOW | RTLD_LOCAL)) {
@@ -333,6 +345,12 @@ auto QDMI_Session_impl_d::querySessionProperty(QDMI_Session_Property prop,
 }
 
 namespace qdmi {
+/**
+ * @brief Constructs the driver and registers built-in static device backends.
+ *
+ * Initializes the driver by creating and storing device entries for the bundled
+ * static libraries: MQT_NA, MQT_DDSIM, and MQT_SC.
+ */
 Driver::Driver() {
   devices_.emplace_back(std::make_unique<QDMI_Device_impl_d>(
       std::make_unique<MQT_NADeviceLibrary>()));
@@ -342,6 +360,11 @@ Driver::Driver() {
       std::make_unique<MQT_SCDeviceLibrary>()));
 }
 
+/**
+ * @brief Releases all resources owned by the Driver.
+ *
+ * Destroys and removes all managed session and device objects so the Driver releases its held resources.
+ */
 Driver::~Driver() {
   sessions_.clear();
   devices_.clear();
@@ -508,4 +531,4 @@ int QDMI_device_query_operation_property(
   }
   return device->queryOperationProperty(operation, numSites, sites, numParams,
                                         params, prop, size, value, sizeRet);
-}
+}