Refine public documentation

Author: bugdea1er

README.md

@@ -73,7 +73,7 @@ The location of temporary files generated by this library is determined by the `
 ...
 {
     // Create a unique temporary file
-    auto tmpfile = tmp::file("org.example.product");
+    auto tmpfile = tmp::file("org.example.product", ".txt");
 
     // Write its contents and metadata
     tmpfile.write(contents);
@@ -106,7 +106,19 @@ To run tests:
 ctest --output-on-failure --test-dir build
 ```
 
-To install the project, run:
+## Installing
+
+To install the project, configure it in the Release configuration:
+```shell
+cmake -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF -DBUILD_SHARED_LIBS=ON
+```
+
+build it:
+```shell
+cmake --build build
+```
+
+and then install:
 ```shell
 sudo cmake --install build
 ```

include/tmp/directory

@@ -20,9 +20,8 @@ namespace tmp {
 /// - the managing tmp::directory object is assigned another path via operator=
 ///
 /// The following example uses a tmp::directory object to create a temporary
-/// directory with the product identifier label; when the function returns,
-/// the tmp::directory object goes out of scope and the temporary directory is
-/// deleted along with all of its contents:
+/// directory; when the function returns, the tmp::directory object goes out of
+/// scope and the temporary directory is deleted along with all of its contents:
 ///
 /// @code{.cpp}
 ///   #include <tmp/directory>
@@ -37,27 +36,22 @@ namespace tmp {
 class TMP_EXPORT directory final : public entry {
 public:
   /// Creates a unique temporary directory
-  ///
-  /// The directory path consists of the system's temporary directory path,
-  /// the given prefix, and random characters to ensure path uniqueness
-  ///
-  /// @param label   A label to attach to the temporary directory path
+  /// @param label     A label to attach to the temporary directory path
   /// @throws std::filesystem::filesystem_error if cannot create a directory
   /// @throws std::invalid_argument             if the label is ill-formatted
   explicit directory(std::string_view label = "");
 
   /// Creates a unique temporary copy recursively from the given path
-  ///
-  /// @param path   A path to make a temporary copy from
-  /// @param label  A label to attach to the temporary directory path
+  /// @param path      A path to make a temporary copy from
+  /// @param label     A label to attach to the temporary directory path
   /// @returns The new temporary directory
-  /// @throws std::filesystem::filesystem_error if @p path is not a directory
+  /// @throws std::filesystem::filesystem_error if given path is not a directory
   /// @throws std::invalid_argument             if the label is ill-formatted
   static directory copy(const std::filesystem::path& path,
                         std::string_view label = "");
 
-  /// Concatenates this directory path with a given @p source
-  /// @param source   A string which represents a path name
+  /// Concatenates this directory path with a given 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;
 

include/tmp/entry

@@ -26,9 +26,8 @@ public:
 
   /// Moves the managed path recursively to a given target, releasing
   /// ownership of the managed path
-  ///
-  /// The parent of the target path is created when this function is called
-  /// @param to   A path to the target file or directory
+  /// @note The target path parent is created when this function is called
+  /// @param to        A path to the target file or directory
   /// @throws std::filesystem::filesystem_error if cannot move the owned path
   void move(const std::filesystem::path& to);
 
@@ -39,21 +38,21 @@ public:
   auto operator=(const entry&) = delete;    ///< not copy-assignable
 
 protected:
-  /// Constructs a tmp::path which owns @p path
-  /// @param path A path to manage
+  /// Creates a temporary entry which owns the given path
+  /// @param path      A path to manage
   explicit entry(std::filesystem::path path);
 
-  /// Releases the ownership of the managed path;
-  /// the destructor will not delete the managed path after the call
-  /// @returns The managed path
-  std::filesystem::path release() noexcept;
-
   entry(entry&&) noexcept;               ///< move-constructible
   entry& operator=(entry&&) noexcept;    ///< move-assignable
 
 private:
   /// The managed path
   std::filesystem::path pathobject;
+
+  /// Releases the ownership of the managed path
+  /// @note the destructor will not delete the managed path after the call
+  /// @returns The full path this entry manages
+  std::filesystem::path release() noexcept;
 };
 }    // namespace tmp
 

include/tmp/file

@@ -15,7 +15,8 @@ namespace tmp {
 /// deletes it when this handle goes out of scope
 ///
 /// When a tmp::file object is created, it creates a unique temporary file using
-/// the system's default location for temporary files
+/// the system's default location for temporary files and opens it for reading
+/// and writing
 ///
 /// The managed file is deleted of when either of the following happens:
 /// - the managing tmp::file object is destroyed
@@ -32,7 +33,7 @@ namespace tmp {
 ///   #include <tmp/file>
 ///
 ///   auto func(std::string_view content) {
-///     auto tmpfile = tmp::file("org.example.product");
+///     auto tmpfile = tmp::file("org.example.product", ".txt");
 ///     tmpfile.write(content);
 ///
 ///     // the temporary file is deleted recursively when the
@@ -52,7 +53,6 @@ public:
 
   /// Creates a unique temporary file and opens it for reading and writing
   /// in binary mode
-  ///
   /// @param label     A label to attach to the temporary file path
   /// @param extension An extension of the temporary file path
   /// @throws std::filesystem::filesystem_error if cannot create a file
@@ -61,7 +61,6 @@ public:
 
   /// Creates a unique temporary file and opens it for reading and writing
   /// in text mode
-  ///
   /// @param label     A label to attach to the temporary file path
   /// @param extension An extension of the temporary file path
   /// @throws std::filesystem::filesystem_error if cannot create a file
@@ -70,12 +69,11 @@ public:
                    std::string_view extension = "");
 
   /// Creates a unique temporary copy from the given path
-  ///
   /// @param path      A path to make a temporary copy from
   /// @param label     A label to attach to the temporary file path
   /// @param extension An extension of the temporary file path
   /// @returns The new temporary file
-  /// @throws std::filesystem::filesystem_error if path is not a file
+  /// @throws std::filesystem::filesystem_error if given path is not a file
   /// @throws std::invalid_argument             if arguments are ill-formatted
   static file copy(const std::filesystem::path& path,
                    std::string_view label = "",
@@ -90,11 +88,11 @@ public:
   std::string read() const;
 
   /// Writes the given content to this file discarding any previous content
-  /// @param content  A string to write to this file
+  /// @param content   A string to write to this file
   void write(std::string_view content) const;
 
   /// Appends the given content to the end of this file
-  /// @param content  A string to append to this file
+  /// @param content   A string to append to this file
   void append(std::string_view content) const;
 
   /// Deletes the managed file if its path is not empty
@@ -114,7 +112,6 @@ private:
 
   /// Creates a unique temporary file and opens it for reading and writing
   /// in the specified mode
-  ///
   /// @param label     A label to attach to the temporary file path
   /// @param extension An extension of the temporary file path
   /// @param binary    Whether the managed file is opened in binary write mode
@@ -123,10 +120,8 @@ private:
   file(std::string_view label, std::string_view extension, bool binary);
 
   /// Creates a unique temporary file
-  ///
-  /// @param handle   A path to the created temporary file and its
-  ///                 implementation-defined handle
-  /// @param binary   Whether the managed file is opened in binary write mode
+  /// @param handle    A path to the created temporary file and its handle
+  /// @param binary    Whether the managed file is opened in binary write mode
   file(std::pair<std::filesystem::path, native_handle_type> handle,
        bool binary) noexcept;
 };