From 3ca949cc2134556df10a31cc45748a2e46d451f4 Mon Sep 17 00:00:00 2001
From: bugdea1er <bugdealer@icloud.com>
Date: Mon, 29 Jan 2024 23:35:00 +0300
Subject: [PATCH] Refine documentaion of tmp::path

---
 include/tmp/path.hpp | 41 +++++++++++++++++++++++++++--------------
 lib/path.cpp         |  2 +-
 2 files changed, 28 insertions(+), 15 deletions(-)

diff --git a/include/tmp/path.hpp b/include/tmp/path.hpp
index 447d3d2..8c23b44 100644
--- a/include/tmp/path.hpp
+++ b/include/tmp/path.hpp
@@ -5,22 +5,28 @@
 
 namespace tmp {
 
-/// The tmp::path class is a smart handle that owns and manages a temporary path
-/// and disposes of it when this handle goes out of scope.
+/// tmp::path is a smart handle that owns and manages a temporary path and
+/// disposes of it when this handle goes out of scope
 ///
-/// Subclass this and provide mktemp-like function to the constructor to create
-/// temporary files and directories.
+/// The managed path is disposed of when either of the following happens:
+/// - the managing tmp::path object is destroyed
+/// - the managing tmp::path object is assigned another path via operator=
+///
+/// Subclass are encouraged to use tmp::path::make_pattern function to obtain
+/// a temporary path pattern suitable for use in mktemp-like functions
 class path {
-    std::filesystem::path underlying;    ///< This path
+    /// The managed path
+    std::filesystem::path underlying;
 
 public:
-    /// Returns the underlying path
+    /// Returns the managed path
     operator const std::filesystem::path&() const noexcept;
 
-    /// Provides access to the underlying path members
+    /// Dereferences the managed path
+    /// @returns A pointer to the path owned by *this
     const std::filesystem::path* operator->() const noexcept;
 
-    /// Deletes this path recursively when the enclosing scope is exited
+    /// Deletes the managed path recursively if it is not empty
     virtual ~path() noexcept;
 
     path(path&&) noexcept;                   ///< move-constructible
@@ -28,14 +34,21 @@ class path {
     path(const path&) = delete;              ///< not copy-constructible
     auto operator=(const path&) = delete;    ///< not copy-assignable
 
-    /// Creates a pattern for the mktemp-like functions.
-    /// If @p prefix is not empty, it is appended to the tempdir
-    static std::string make_pattern(std::string_view prefix);
+    /// Creates a path pattern with the given prefix
+    ///
+    /// The pattern consists of the system's temporary directory path, the given
+    /// prefix, and six 'X' characters that must be replaced by random
+    /// characters to ensure uniqueness
+    ///
+    /// The parent of the resulting path is created when this function is called
+    /// @param prefix   A prefix to be used in the path pattern
+    /// @returns A path pattern for the unique temporary path
+    /// @throws std::filesystem::filesystem_error if failed to create the parent
+    static std::filesystem::path make_pattern(std::string_view prefix);
 
 protected:
-    /// Creates a unique temporary path using the given constructor function.
-    /// @param prefix the path between system temp
-    /// @param creator wrapped mktemp-like function that returns resulting path
+    /// Constructs a tmp::path which owns @p path
+    /// @param path A path to manage
     explicit path(std::filesystem::path path);
 };
 
diff --git a/lib/path.cpp b/lib/path.cpp
index 2a7b641..5e905d2 100644
--- a/lib/path.cpp
+++ b/lib/path.cpp
@@ -47,7 +47,7 @@ const fs::path* path::operator->() const noexcept {
     return std::addressof(underlying);
 }
 
-std::string path::make_pattern(std::string_view prefix) {
+fs::path path::make_pattern(std::string_view prefix) {
     fs::path parent = fs::temp_directory_path() / prefix;
     fs::create_directories(parent);