kapi/devices: improve documentation

1 files changed, 50 insertions, 14 deletions

diff --git a/kapi/kapi/devices/device.hpp b/kapi/kapi/devices/device.hpp
index 3f8a52d7..50fc10b6 100644
--- a/kapi/kapi/devices/device.hpp
+++ b/kapi/kapi/devices/device.hpp
@@ -15,60 +15,90 @@ namespace kapi::devices
   //! @addtogroup kapi-devices-kernel-defined
   //! @{
 
+  //! The possible states of a device.
   enum struct state
   {
+    //! The device has been created but not attached to any bus.
     uninitialized,
+    //! The device has been attached to a bus.
     present,
+    //! The device is being probed by a driver.
     probing,
+    //! The device has been bound to a driver.
     bound,
+    //! The device has failed in that no driver was able to bind it.
     failed,
+    //! The device has been removed from its bus.
     removed,
   };
 
-  /**
-   * @brief Base device identified by a name.
-   */
+  //! An inert tree device.
+  //!
+  //! Devices themselves carry no logic. They are inert nodes in the device tree, used to bind drivers and own driver
+  //! data.
   struct device : kstd::enable_shared_from_this<device>
   {
-    /**
-     * @brief Create a device identified by @p name.
-     * @param name Device name.
-     */
+    //! Create a new device with a given tree name.
+    //!
+    //! @param name The desired tree name for the device.
     explicit device(kstd::string const & name);
 
-    /**
-     * @brief Virtual destructor for device.
-     */
+    //! Enable safe destruction through base pointers.
     virtual ~device() = default;
 
+    //! Get a given capability from this device, if it implements it.
+    //!
+    //! @param interface The id of the desired interface.
+    //! @return An opaque pointer to the interface implementation if this device supports it, nullptr otherwise.
     [[nodiscard]] auto as(interface_id interface) noexcept -> void *;
 
+    //! Get a given capability from this device, if it implements it.
+    //!
+    //! @param interface The id of the desired interface.
+    //! @return A opaque pointer to the interface implementation if this device supports it, nullptr otherwise.
     [[nodiscard]] auto as(interface_id interface) const noexcept -> void const *;
 
+    //! Get a given capability from this device, if it implements it.
+    //!
+    //! @tparam Interface The id of the desired interface.
+    //! @return A typed pointer to the interface implementation if this device supports it, nullptr otherwise.
     template<typename InterfaceType>
     [[nodiscard]] auto as() -> InterfaceType *
     {
       return static_cast<InterfaceType *>(as(InterfaceType::id));
     }
 
+    //! Get a given capability from this device, if it implements it.
+    //!
+    //! @tparam Interface The id of the desired interface.
+    //! @return A typed pointer to the interface implementation if this device supports it, nullptr otherwise.
     template<typename InterfaceType>
     [[nodiscard]] auto as() const noexcept -> InterfaceType const *
     {
       return static_cast<InterfaceType const *>(as(InterfaceType::id));
     }
 
+    //! Check if this device implements a given capability interface.
+    //!
+    //! @param interface The id of the queried interface.
+    //! @return true iff. this device implements the given interface, false otherwise.
     [[nodiscard]] auto is_a(interface_id interface) const noexcept -> bool;
 
+    //! Check if this device implements a given capability interface.
+    //!
+    //! @tparam Interface The id of the queried interface.
+    //! @return true iff. this device implements the given interface, false otherwise.
     template<typename InterfaceType>
     [[nodiscard]] auto is_a() const noexcept -> bool
     {
       return is_a(InterfaceType::id);
     }
 
-    /**
-     * @brief Returns the name of the device.
-     * @return Device name.
-     */
+    //! Get the name of the device.
+    //!
+    //! Device names are not stable names, but rather unique tree names.
+    //!
+    //! @return The tree name of this device.
     [[nodiscard]] auto name() const -> kstd::string const &;
 
     //! Get the parent bus of this device.
@@ -98,8 +128,14 @@ namespace kapi::devices
     auto virtual query_interface(interface_id interface) -> void *;
 
   private:
+    //! Busses need to be able to register themselves as a device's parent.
     friend struct bus;
 
+    //! Set the parent bus of this device.
+    //!
+    //! This functions is used by busses to establish the back-pointer in their children.
+    //!
+    //! @param parent The new parent bus of this device.
     auto set_parent(kstd::weak_ptr<struct bus> parent) -> void;
 
     kstd::string m_name;