From 36332dff40d1c2432918f8486b67a71c2b48dcfa Mon Sep 17 00:00:00 2001
From: q66 <daniel@octaforge.org>
Date: Wed, 5 Apr 2017 20:53:14 +0200
Subject: [PATCH] document environ and filesystem

---
 ostd/environ.hh    | 62 +++++++++++++++++++++++++++++++++++++++++++---
 ostd/filesystem.hh | 55 ++++++++++++++++++++++++++++++++++++++--
 2 files changed, 111 insertions(+), 6 deletions(-)

diff --git a/ostd/environ.hh b/ostd/environ.hh
index 019a674..7fc9f43 100644
--- a/ostd/environ.hh
+++ b/ostd/environ.hh
@@ -1,6 +1,18 @@
-/* Environment handling.
+/** @defgroup Utilities
  *
- * This file is part of OctaSTD. See COPYING.md for futher information.
+ * @brief Miscellaneous utilities.
+ *
+ * @{
+ */
+
+/** @file environ.hh
+ *
+ * @brief A portable environment variable interface.
+ *
+ * Provides utility functions to portably get, set and unset environment
+ * variables.
+ *
+ * @copyright See COPYING.md in the project tree for further information.
  */
 
 #ifndef OSTD_ENVIRON_HH
@@ -17,10 +29,24 @@
 
 #include "ostd/string.hh"
 
-/* TODO: make POSIX version thread safe, the Windows version is... */
-
 namespace ostd {
 
+/** @addtogroup Utilities
+ * @{
+ */
+
+/** @brief Gets an environment variable.
+ *
+ * @returns std::nullopt when the variable doesn't exist, and an std::string
+ * containing the environment variable's value if it does.
+ *
+ * This function is thread-safe as long as the environment is not modified
+ * within the program. Calling to lower level functions to set environment
+ * vars as well as env_set() or env_unset() at the same time would introduce
+ * potential data races.
+ *
+ * @see env_set(), env_unset()
+ */
 inline std::optional<std::string> env_get(string_range name) {
     char buf[256];
     auto tbuf = to_temp_cstr(name, buf, sizeof(buf));
@@ -47,6 +73,20 @@ inline std::optional<std::string> env_get(string_range name) {
 #endif
 }
 
+/** @brief Sets an environment variable.
+ *
+ * If `update` is false, the environment variable will not be overwritten
+ * if it already exists. Keep in mind that true is still returned if the
+ * variable already exists and it's not being updated.
+ *
+ * This function is not thread safe. Do not call it from multiple threads
+ * and do not call it if a call to env_get() might be done from another
+ * thread at the time.
+ *
+ * @returns true on success, false on failure.
+ *
+ * @see env_get(), env_unset()
+ */
 inline bool env_set(
     string_range name, string_range value, bool update = true
 ) {
@@ -74,6 +114,16 @@ inline bool env_set(
     return ret;
 }
 
+/** @brief Unsets an environment varible.
+ *
+ * This function is not thread safe. Do not call it from multiple threads
+ * and do not call it if a call to env_get() might be done from another
+ * thread at the time.
+ *
+ * @returns true on success, false on failure.
+ *
+ * @see env_get(), env_set()
+ */
 inline bool env_unset(string_range name) {
     char buf[256];
     if (name.size() < sizeof(buf)) {
@@ -92,6 +142,10 @@ inline bool env_unset(string_range name) {
 #endif
 }
 
+/** @} */
+
 } /* namespace ostd */
 
 #endif
+
+/** @} */
diff --git a/ostd/filesystem.hh b/ostd/filesystem.hh
index bea7039..b3148f5 100644
--- a/ostd/filesystem.hh
+++ b/ostd/filesystem.hh
@@ -1,6 +1,20 @@
-/* Filesystem API for OctaSTD. Currently POSIX only.
+/** @addtogroup Utilities
+ * @{
+ */
+
+/** @file filesystem.hh
  *
- * This file is part of OctaSTD. See COPYING.md for futher information.
+ * @brief Filesystem abstraction module.
+ *
+ * This module defines the namespace ostd::filesystem, which is either
+ * std::experimental::filesystem or std::filesystem depending on which
+ * is available. For portable applications, only use the subset of the
+ * module covered by both versions.
+ *
+ * It also provides range integration for directory iterators and
+ * ostd::format_traits specialization for std::filesystem::path.
+ *
+ * @copyright See COPYING.md in the project tree for further information.
  */
 
 #ifndef OSTD_FILESYSTEM_HH
@@ -25,26 +39,59 @@ namespace ostd {
 
 namespace ostd {
 
+/** @addtogroup Utilities
+ * @{
+ */
+
+/** @brief Range integration for std::filesystem::directory_iterator.
+ *
+ * Allows directory iterators to be made into ranges via ostd::iter().
+ *
+ * @see ostd::ranged_traits<filesystem::recursive_directory_iterator>
+ */
 template<>
 struct ranged_traits<filesystem::directory_iterator> {
+    /** @brief The range type for the iterator. */
     using range = iterator_range<filesystem::directory_iterator>;
 
+    /** @brief Creates a range for the iterator. */
     static range iter(filesystem::directory_iterator const &r) {
         return range{filesystem::begin(r), filesystem::end(r)};
     }
 };
 
+/** @brief Range integration for std::filesystem::recursive_directory_iterator.
+ *
+ * Allows recursive directory iterators to be made into ranges via ostd::iter().
+ *
+ * @see ostd::ranged_traits<filesystem::directory_iterator>
+ */
 template<>
 struct ranged_traits<filesystem::recursive_directory_iterator> {
+    /** @brief The range type for the iterator. */
     using range = iterator_range<filesystem::recursive_directory_iterator>;
 
+    /** @brief Creates a range for the iterator. */
     static range iter(filesystem::recursive_directory_iterator const &r) {
         return range{filesystem::begin(r), filesystem::end(r)};
     }
 };
 
+/** @brief ostd::format_traits specialization for std::filesystem::path.
+ *
+ * This allows paths to be formatted as strings. The value is formatted
+ * as if `path.string()` was formatted, using the exact ostd::format_spec.
+ */
 template<>
 struct format_traits<filesystem::path> {
+    /** @brief Formats the path's string value.
+     *
+     * This calls exactly
+     *
+     * ~~~{.cc}
+     * fs.format_value(writer, p.string());
+     * ~~~
+     */
     template<typename R>
     static void to_format(
         filesystem::path const &p, R &writer, format_spec const &fs
@@ -53,6 +100,10 @@ struct format_traits<filesystem::path> {
     }
 };
 
+/** @} */
+
 } /* namespace ostd */
 
 #endif
+
+/** @} */