Prepare for new SSO.

1 files changed, 57 insertions, 4 deletions

diff --git a/include/libfud.hpp b/include/libfud.hpp
index bff791d..f0a2517 100644
--- a/include/libfud.hpp
+++ b/include/libfud.hpp
@@ -26,6 +26,8 @@
 
 #include <cstdint>
 
+/** @file */
+
 namespace fud {
 
 constexpr size_t GIT_REV_CHARS = 13;
@@ -37,7 +39,10 @@ struct FUD {
     Array<char, GIT_REV_CHARS> revision;
 };
 
-/** \brief Get the version of FUD including git revision. */
+/** \brief Get the version of FUD including git revision.
+ *
+ * \returns FUD object with verison information.
+ */
 FUD fud();
 
 /**
@@ -46,23 +51,71 @@ FUD fud();
  * \param[in] name The name of the variable to look up.
  * \param[in] allocator The allocator used by the string returned.
  *
- * \retstmt The value of the string bound to the variable if it exists.
- * \retcode FudStatus::NullPointer if name is a null pointer.
- * \retcode FudStatus::NotFound if no binding for the variable exists.
+ * \returns The value of the string bound to the variable if it exists.
+ * \returns FudStatus::NullPointer if name is a null pointer.
+ * \returns FudStatus::NotFound if no binding for the variable exists.
  */
 Result<String, FudStatus> getEnv(const char* name, Allocator* allocator= &globalFudAllocator);
 
+/** \brief A concept requiring the object T to have a method c_str returning a
+ * pointer to a C string. */
 template <typename T>
 concept CStringRepr = requires(T strObj) {
     { strObj.c_str() } -> std::convertible_to<const char*>;
 };
 
+/**
+ * \brief Get an environmental variable if it exists.
+ *
+ * \tparam T A type which has a method c_str returning a pointer convertible to
+ * a C string.
+ * \param[in] name The name of the variable to look up.
+ * \param[in] allocator The allocator used by the string returned.
+ *
+ * \returns @getEnv return values.
+ */
 template <CStringRepr T>
 Result<String, FudStatus> getEnv(const T& name, Allocator* allocator = &globalFudAllocator)
 {
     return getEnv(name.c_str(), allocator);
 }
 
+/** \mainpage libfud
+ *
+ * \section intro_sec Introduction
+ *
+ * libfud is an exception-free, UB-minimizing, library for safely making system
+ * calls, handling UTF8 encoded strings, and managing containers with user
+ * controlled allocators.
+ *
+ * \subsection design_principles Design Principles
+ *
+ * - Full control over allocations, even the default allocator.
+ * - Zero exceptions, zero exceptions to zero exceptions.
+ * - Assertions in production release for invariants.
+ * - Configurable run-time assertions for indexing.
+ * - Safe API for users intolerant to run-time assertions for indexing.
+ * - Readable, understandable code.
+ * - Minimize undefined behavior in the API to a subset which is only decidable at
+ *   run-time.
+ * - Minimize runtime undefined behavior as much as possible.
+ *
+ * \subsection rel_mature_features Relatively Mature Features
+ *
+ * - Statically sized Array
+ * - StringView
+ *
+ * \subsection unstable_features Unstable Features
+ *
+ * - Customizable allocator model
+ * - Dynamically sized Vector taking an allocator
+ * - Dynamically sized String taking an allocator
+ * - Unicode support with UTF8 encoding
+ * - format à la =std::format=
+ * - Wrappers around C files
+ *
+ */
+
 } // namespace fud
 
 #endif