Refine documentaion of tmp::directory and tmp::file methods

include/tmp/directory.hpp

@@ -39,16 +39,21 @@ namespace tmp {
 /// deleted along with all of its contents.
 class directory final : public path {
 public:
-    /// Creates a unique temporary directory using the system's default location
-    /// for temporary files. If a prefix is provided to the constructor, the
-    /// directory is created in the path <temp dir>/prefix/. The prefix can be
-    /// a path consisting of multiple segments.
+    /// Creates a unique temporary directory
+    ///
+    /// The directory path consists of the system's temporary directory path,
+    /// the given prefix, and six random characters to ensure path uniqueness
+    ///
+    /// @param prefix   A prefix to be used in the temporary directory path
+    /// @throws std::filesystem::filesystem_error if cannot create a directory
     explicit directory(std::string_view prefix = "");
 
     /// Concatenates this directory path with a given @p source
+    /// @param source   A string which represents a path name
+    /// @returns The result of path concatenation
     std::filesystem::path operator/(std::string_view source) const;
 
-    /// Deletes this directory recursively when the enclosing scope is exited
+    /// Deletes the managed directory recursively if its path is not empty
     ~directory() noexcept override;
 
     directory(directory&&) noexcept;               ///< move-constructible

include/tmp/file.hpp

@@ -46,25 +46,33 @@ namespace tmp {
 /// object goes out of scope and the temporary file is deleted.
 class file final : public path {
 public:
-    /// Creates a unique temporary binary file using the system's default
-    /// location for temporary files. If a prefix is provided to the
-    /// constructor, the directory is created in the path <temp dir>/prefix/.
-    /// The prefix can be a path consisting of multiple segments.
+    /// Creates a unique temporary binary file
+    ///
+    /// The file path consists of the system's temporary directory path, the
+    /// given prefix, and six random characters to ensure path uniqueness
+    ///
+    /// @param prefix   A prefix to be used in the temporary file path
+    /// @throws std::filesystem::filesystem_error if cannot create a file
     explicit file(std::string_view prefix = "");
 
-    /// Creates a unique temporary text file using the system's default location
-    /// for temporary files. If a prefix is provided to the constructor, the
-    /// directory is created in the path <temp dir>/prefix/. The prefix can be
-    /// a path consisting of multiple segments.
+    /// Creates a unique temporary text file
+    ///
+    /// The file path consists of the system's temporary directory path, the
+    /// given prefix, and six random characters to ensure path uniqueness
+    ///
+    /// @param prefix   A prefix to be used in the temporary file path
+    /// @throws std::filesystem::filesystem_error if cannot create a file
     static file text(std::string_view prefix = "");
 
-    /// Writes the given @p content to this file discarding any previous content
+    /// Writes the given content to this file discarding any previous content
+    /// @param content  A string to write to this file
     void write(std::string_view content) const;
 
-    /// Appends the given @p content to the end of this file
+    /// Appends the given content to the end of this file
+    /// @param content  A string to append to this file
     void append(std::string_view content) const;
 
-    /// Deletes this file when the enclosing scope is exited
+    /// Deletes the managed file if its path is not empty
     ~file() noexcept override;
 
     file(file&&) noexcept;                   ///< move-constructible
@@ -73,12 +81,17 @@ class file final : public path {
     auto operator=(const file&) = delete;    ///< not copy-assignable
 
 private:
-    bool binary;    ///< This file write mode
+    /// Whether the managed file is opened in binary write mode
+    bool binary;
 
-    /// Creates a unique temporary file using the system's default location
-    /// for temporary files. If a prefix is provided to the constructor, the
-    /// directory is created in the path <temp dir>/prefix/. The prefix can be
-    /// a path consisting of multiple segments.
+    /// Creates a unique temporary file
+    ///
+    /// The file path consists of the system's temporary directory path, the
+    /// given prefix, and six random characters to ensure path uniqueness
+    ///
+    /// @param prefix   A prefix to be used in the temporary file path
+    /// @param binary   Whether the managed file is opened in binary write mode
+    /// @throws std::filesystem::filesystem_error if cannot create a file
     explicit file(std::string_view prefix, bool binary);
 };