Tidy up documentation

include/tmp/path.hpp

@@ -2,7 +2,6 @@
 
 #include <filesystem>
 #include <string_view>
-#include <system_error>
 
 namespace tmp {
 

lib/file.cpp

@@ -7,7 +7,11 @@ namespace tmp {
 
 namespace {
 
-/// Returns a stream for this file
+/// Opens a temporary file for writing and returns an output file stream
+/// @param file The file to open
+/// @param binary Whether to open the file in binary mode (true) or text mode (false)
+/// @param append Whether to append to the end of the file (true) or truncate it (false)
+/// @return An output file stream
 std::ofstream stream(const file& file, bool binary, bool append) noexcept {
     std::ios::openmode mode = append ? std::ios::app : std::ios::trunc;
     auto path = static_cast<const std::filesystem::path&>(file);

lib/path.cpp

@@ -1,12 +1,13 @@
 #include <tmp/path.hpp>
 
+#include <system_error>
 #include <utility>
 
-namespace tmp {
-
 namespace {
 
-/// Deletes the given path recursively, ignoring any errors
+/// Deletes the given path recursively, ignoring any errors.
+/// If the path is empty, does nothing.
+/// @param path The path of the directory to remove
 void remove(const tmp::path& path) noexcept {
     if (!path->empty()) {
         std::error_code ec;
@@ -16,6 +17,8 @@ void remove(const tmp::path& path) noexcept {
 
 }    // namespace
 
+namespace tmp {
+
 path::path(path&& other) noexcept : underlying(std::move(other.underlying)) {
     other.underlying.clear();
 }
@@ -39,14 +42,9 @@ const std::filesystem::path* path::operator->() const noexcept {
     return std::addressof(this->underlying);
 }
 
-/// 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
 path::path(std::filesystem::path path) : underlying(std::move(path)) {
 }
 
-/// Creates a pattern for the mktemp-like functions.
-/// If @p prefix is not empty, it is appended to the tempdir
 std::string path::make_pattern(std::string_view prefix) {
     const auto parent = std::filesystem::temp_directory_path() / prefix;
     std::filesystem::create_directories(parent);