1 files changed, 44 insertions, 53 deletions

diff --git a/kernel/kernel/filesystem/dentry.hpp b/kernel/kernel/filesystem/dentry.hpp
index ea689485..30d8c4f9 100644
--- a/kernel/kernel/filesystem/dentry.hpp
+++ b/kernel/kernel/filesystem/dentry.hpp
@@ -12,84 +12,75 @@
 
 namespace kernel::filesystem
 {
-  /**
-  @brief Represents a directory entry (dentry) in the filesystem. A dentry is a node in the directory tree that
-  represents a file or directory. It contains a reference to its parent dentry, a reference to the associated real
-  filesystem inode, and a list of child dentries.
-  */
+  //! A directory entry in the filesystem.
   struct dentry
   {
-    /**
-    @brief Flags for the dentry.
-    */
+    //! Flags for the dentry.
     enum class dentry_flags : uint32_t
     {
       is_mount_point = 1 << 0
     };
 
-    /**
-    @brief Create a dentry with the given @p parent, associated @p inode, and optional @p name. The dentry is
-    initialized with the provided parent and inode, and the name is stored for lookup purposes.
-    @param parent The parent dentry.
-    @param inode The associated inode for this dentry.
-    @param name The name of the dentry (optional).
-    */
+    //! Create a directory entry with the given parent, associated inode, and name.
+    //!
+    //! @warning This function will panic if invoked with a null pointer for the inode argument.
+    //!
+    //! @param parent The parent directory entry, if any.
+    //! @param inode The associated inode for this dentry.
+    //! @param name The name of the dentry.
     dentry(kstd::shared_ptr<dentry> const & parent, kstd::shared_ptr<inode> const & inode, std::string_view name);
 
-    /**
-    @brief Get the associated inode.
-    @return A reference to the associated inode.
-    */
+    //! Get this entrys associated inode.
+    //!
+    //! @return The inode associated with this directory entry.
     [[nodiscard]] auto get_inode() const -> kstd::shared_ptr<inode> const &;
 
-    /**
-    @brief Get the parent dentry.
-    @return A reference to the parent dentry.
-    */
+    //! Get this entrys parent directory entry.
+    //!
+    //! @return The parent directory entry, or @p nullptr if this entry has no parent.
     [[nodiscard]] auto parent() const -> kstd::shared_ptr<dentry>;
 
-    /**
-    @brief Get the name of the dentry.
-    @return The name of the dentry.
-    */
+    //! Get this entrys name.
+    //!
+    //! @return The name of this directory entry.
     [[nodiscard]] auto name() const -> std::string_view;
 
-    /**
-      @brief Get the full path of the dentry by traversing up to the root.
-      @return The full path of the dentry.
-     */
+    //! Get the full path of this entry by traversing up to the root.
+    //!
+    //! @note This function performs a full path traversal to the root. Even if all entries on that path a cached, this
+    //! may imply a non insignificant time penalty, as traversal complexity is linear in the depth of the path.
+    //!
+    //! @return The full path of this directory entry.
     [[nodiscard]] auto absolute_path() const -> kstd::string;
 
-    /**
-    @brief Add a @p child dentry.
-    @param child The child dentry to add.
-    */
+    //! Add a child to this entry.
+    //!
+    //! @param child The child directory entry to add.
     auto add_child(kstd::shared_ptr<dentry> const & child) -> void;
 
-    /**
-    @brief Find a child dentry by @p name.
-    @param name The name of the child dentry to find.
-    @return A pointer to the found child dentry, or a null pointer if not found.
-    */
+    //! Find a child entry with the given name.
+    //!
+    //! @note This function performs no path traversal. The name supplied to this function must name a direct child of
+    //! this directory entry in order for it to be found.
+    //!
+    //! @param name The name of the child directory entry to find.
+    //! @return A pointer to the child dentry if it exists, a null pointer otherwise.
     [[nodiscard]] auto find_child(std::string_view name) const -> kstd::shared_ptr<dentry>;
 
-    /**
-    @brief Set a @p flag for the dentry.
-    @param flag The flag to set.
-    */
+    //! Set a flag for this entry.
+    //!
+    //! @param flag The flag to set.
     auto set_flag(dentry_flags flag) -> void;
 
-    /**
-    @brief Unset a @p flag for the dentry.
-    @param flag The flag to unset.
-    */
+    //! Clear a flag from this entry.
+    //!
+    //! @param flag The flag to clear.
     auto unset_flag(dentry_flags flag) -> void;
 
-    /**
-    @brief Check if the dentry has a specific @p flag.
-    @param flag The flag to check.
-    @return True if the dentry has the flag, false otherwise.
-    */
+    //! Check if this entry has a specific flag set.
+    //!
+    //! @param flag The flag to check.
+    //! @return @c true iff. the flag is set on this entry, @c false otherwise.
     [[nodiscard]] auto has_flag(dentry_flags flag) const -> bool;
 
   private: