Rewrite documentation (#196)

Rewrite documentation and sync examples in the public headers and README

Author: bugdea1er

README.md

@@ -7,6 +7,7 @@ This library provides functionality for efficient management of temporary files
 ![Static Badge](https://img.shields.io/badge/C%2B%2B-17%2B-blue)
 ![GitHub Tag](https://img.shields.io/github/v/release/bugdea1er/tmp)
 
+
 ## Overview
 
 When developing applications with long uptimes, such as server software, the management of temporary files and directories can become crucial. While the system may eventually clean up temporary files, this process may not occur frequently enough to meet the needs of applications with extended operational periods. Relying solely on the system for this task may lead to an accumulation of unnecessary temporary data on the device.
@@ -26,68 +27,54 @@ The location of temporary files generated by this library is determined by the `
 
 ### Temporary directories
 
-`tmp::directory` is a RAII-handle for unique temporary directories. This can be useful for:
-
-1. **Batch Processing:** Temporary directories can be used during batch processing tasks where multiple files need to be processed in a specific order. For example, a script that processes a large number of images may create temporary directories to organize and manage the input and output files efficiently.
-
-2. **Software Installation:** Temporary directories are commonly used during software installation processes to store temporary files needed for installation. For instance, when installing a new application, temporary directories can be used to extract installation packages and store temporary configuration files.
+`tmp::directory` is a smart handle that manages a temporary directory, ensuring its recursive deletion when the handle goes out of scope. When a `tmp::directory` object is created, it generates a unique temporary directory in the current user's temporary directory.
 
-3. **Data Backup:** Temporary directories can be utilized for creating temporary backups of important data before performing critical operations. For example, before making changes to a database, a temporary directory can be used to store a backup copy of the database to ensure data integrity.
+The temporary directory is deleted when either of the following happens: 
+- the `tmp::directory` object is destroyed
+- the `tmp::directory` object is assigned another directory using `operator=`
 
-4. **File Compression:** Temporary directories are often used during file compression tasks where multiple files need to be compressed into a single archive. For instance, when creating a zip file containing multiple documents, a temporary directory can be used to store the compressed files before creating the final archive.
-
-5. **Data Migration:** Temporary directories can be helpful during data migration processes where data needs to be transferred from one system to another. For example, when migrating data from a legacy system to a new system, temporary directories can be used to stage and process the data before final migration.
+The example below demonstrates a usage of a `tmp::directory` object to run a subprocess within it and archive its logs; when the function returns, the temporary directory is recursively deleted:
 
 ```cpp
 #include <tmp/directory>
-...
-{
-    // Create a unique temporary directory
-    auto tmpdir = tmp::directory("org.example.product");
-
-    // Populate this directory
-    fs::copy(file1, tmpdir);
-    fs::copy(file2, tmpdir);
-
-    // Make an archive from this directory
-    archiver::zip(tmpdir);
-}   // The directory will be deleted when exiting the scope
-```
 
-### Temporary files
+auto func() {
+  auto tmpdir = tmp::directory("org.example.product");
+  process::exec(executable, args, tmpdir);
 
-`tmp::file` is a RAII-handle for unique temporary files. This can be useful for:
+  return archive::glob(tmpdir, "*.log");
 
-1. **Caching:** Temporary files can be used to cache data that needs to be accessed frequently but doesn't need to be stored permanently. For example, a web application can store pre-rendered HTML pages in temporary files to improve performance by serving them quickly without re-generating them each time.
+  // The temporary directory is deleted recursively when the
+  // tmp::directory object goes out of scope
+}
+```
 
-2. **Data Processing:** Temporary files are often used during data processing tasks where intermediate results need to be stored temporarily before further processing. For instance, a script that manipulates a large dataset may write intermediate results to temporary files to avoid memory constraints.
+### Temporary files
 
-3. **File Conversion:** Temporary files can be utilized during file format conversions. For instance, when converting a video file from one format to another, temporary files can be used to store the partially converted data before completing the conversion process.
+`tmp::file` is a smart handle that manages a temporary file, ensuring its deletion when the handle goes out of scope. Upon creation, a `tmp::file` object generates a unique temporary file in the current user's temporary directory, opening it for both reading and writing.
 
-4. **Testing:** Temporary files can be handy during testing scenarios where you need to create mock data or simulate certain conditions. For example, a unit test for a file upload feature might create a temporary file to mimic the behavior of an uploaded file without actually saving it permanently.
+The temporary file is deleted of when either of the following happens:
+- the `tmp::file` object is destroyed
+- the `tmp::file` object is assigned another file using `operator=`
 
-5. **Logging:** Temporary files can also be used for logging purposes, where log data is written to a temporary file before being processed and stored in a more permanent location. This can be helpful for managing log data efficiently in high-traffic systems.
+`tmp::file` inherits from the `std::iostream` class, allowing it to be used seamlessly with standard input/output operations and simplifying file handling while maintaining the flexibility of stream operations.
 
-`tmp::file` extends the `std::iostream` class and uses an instance of `std::filebuf` internally. It is essentially `std::fstream` without open/close methods
+The example below demonstrates a usage of a tmp::file object to validate a request content and then move it to persistent storage; note that after the `move()` call, the temporary file will not be deleted, as its ownership is transferred to the specified location:
 
 ```cpp
 #include <tmp/file>
-...
-{
-    // Create a unique temporary file
-    auto tmpfile = tmp::file(std::ios::binary);
-
-    // Write its contents and metadata
-    tmpfile << contents << metadata;
-
-    // Validate the file with an external validator
-    if (validate(tmpfile)) {
-        // Save the file to the persistent storage
-        tmpfile.move(storage / "new_file");
-    } else {
-        throw InvalidRequestError();
-    }
-}   // The file will be deleted when exiting the scope
+
+auto func(std::string_view content) {
+  auto tmpfile = tmp::file(std::ios::binary);
+  tmpfile << contents << std::flush;
+  if (validate(tmpfile)) {
+    // Save the file to the persistent storage
+    tmpfile.move(storage / "new_file");
+  } else {
+    // The file is deleted automatically
+    throw InvalidRequestError();
+  }
+}
 ```
 
 ## Building

include/tmp/directory

@@ -9,30 +9,31 @@
 
 namespace tmp {
 
-/// `tmp::directory` is a smart handle that owns and manages a temporary
-/// directory and deletes it recursively when this handle goes out of scope
+/// tmp::directory is a smart handle that manages a temporary directory,
+/// ensuring its recursive deletion when the handle goes out of scope
 ///
-/// When a `tmp::directory` object is created, it creates a unique temporary
+/// When a tmp::directory object is created, it generates a unique temporary
 /// directory in the current user's temporary directory
 ///
-/// The managed directory is deleted of when either of the following happens:
-/// - the managing `tmp::directory` object is destroyed
-/// - the managing `tmp::directory` object is assigned another path
-///   via `operator=`
+/// The temporary directory is deleted when either of the following happens:
+/// - the tmp::directory object is destroyed
+/// - the tmp::directory object is assigned another directory using operator=
 ///
-/// The following example uses a `tmp::directory` object to create a temporary
-/// directory; when the function returns, the `tmp::directory` object goes out
-/// of scope and the temporary directory is recursively deleted:
+/// The example below demonstrates a usage of a tmp::directory object to run
+/// a subprocess within it and archive its logs; when the function
+/// returns, the temporary directory is recursively deleted:
 ///
 /// @code{.cpp}
 ///   #include <tmp/directory>
 ///
 ///   auto func() {
 ///     auto tmpdir = tmp::directory("org.example.product");
-///     std::ostream(tmpdir / "file.txt") << "Hello, world!";
+///     process::exec(executable, args, tmpdir);
 ///
-///     // the temporary directory is deleted recursively when the
-///     // `tmp::directory` object goes out of scope and is destroyed
+///     return archive::glob(tmpdir, "*.log");
+///
+///     // The temporary directory is deleted recursively when the
+///     // tmp::directory object goes out of scope
 ///   }
 /// @endcode
 class directory {

include/tmp/file

@@ -13,34 +13,39 @@
 
 namespace tmp {
 
-/// `tmp::file` is a smart handle that owns and manages a temporary file and
-/// deletes it when this handle goes out of scope
+/// tmp::file is a smart handle that manages a temporary file, ensuring
+/// its deletion when the handle goes out of scope
 ///
-/// When a `tmp::file` object is created, it creates a unique temporary file
-/// in the current user's temporary directory and opens it with
-/// for reading and writing
+/// Upon creation, a tmp::file object generates a unique temporary file
+/// in the current user's temporary directory, opening it for both
+/// reading and writing
 ///
-/// The managed file is deleted of when either of the following happens:
-/// - the managing `tmp::file` object is destroyed
-/// - the managing `tmp::file` object is assigned another path via `operator=`
+/// The temporary file is deleted of when either of the following happens:
+/// - the tmp::file object is destroyed
+/// - the tmp::file object is assigned another file using operator=
 ///
-/// `tmp::file` extends the `std::iostream` class and uses an instance
-/// of `std::filebuf` internally. It is essentially `std::fstream`
-/// without open/close methods
+/// tmp::file inherits from the std::iostream class, allowing it to be
+/// used seamlessly with standard input/output operations and simplifying file
+/// handling while maintaining the flexibility of stream operations
 ///
-/// The following example uses a `tmp::file` object to create a temporary file
-/// and write a string to it; when the function returns, the `tmp::file` object
-/// goes out of scope and the temporary file is deleted:
+/// The example below demonstrates a usage of a tmp::file object to validate
+/// a request content and then move it to persistent storage; note that after
+/// the move() call, the temporary file will not be deleted, as its ownership
+/// is transferred to the specified location:
 ///
 /// @code{.cpp}
 ///   #include <tmp/file>
 ///
 ///   auto func(std::string_view content) {
-///     auto tmpfile = tmp::file(std::ios::bin);
-///     tmpfile << content << std::flush;
-///
-///     // the temporary file is deleted recursively when the
-///     // `tmp::file` object goes out of scope and is destroyed
+///     auto tmpfile = tmp::file(std::ios::binary);
+///     tmpfile << contents << std::flush;
+///     if (validate(tmpfile)) {
+///       // Save the file to the persistent storage
+///       tmpfile.move(storage / "new_file");
+///     } else {
+///       // The file is deleted automatically
+///       throw InvalidRequestError();
+///     }
 ///   }
 /// @endcode
 class file : public std::iostream {