Extend internal API docs, part 2

Picking up from #8111.

Co-authored-by: Eelco Dolstra <edolstra@gmail.com>

1 files changed, 29 insertions, 17 deletions

diff --git a/src/libutil/types.hh b/src/libutil/types.hh
index 6bcbd7e1d..cef34525b 100644
--- a/src/libutil/types.hh
+++ b/src/libutil/types.hh
@@ -17,7 +17,9 @@ typedef std::set<std::string> StringSet;
 typedef std::map<std::string, std::string> StringMap;
 typedef std::map<std::string, std::string> StringPairs;
 
-/* Paths are just strings. */
+/**
+ * Paths are just strings.
+ */
 typedef std::string Path;
 typedef std::string_view PathView;
 typedef std::list<Path> Paths;
@@ -25,15 +27,19 @@ typedef std::set<Path> PathSet;
 
 typedef std::vector<std::pair<std::string, std::string>> Headers;
 
-/* Helper class to run code at startup. */
+/**
+ * Helper class to run code at startup.
+ */
 template<typename T>
 struct OnStartup
 {
     OnStartup(T && t) { t(); }
 };
 
-/* Wrap bools to prevent string literals (i.e. 'char *') from being
-   cast to a bool in Attr. */
+/**
+ * Wrap bools to prevent string literals (i.e. 'char *') from being
+ * cast to a bool in Attr.
+ */
 template<typename T>
 struct Explicit {
     T t;
@@ -45,21 +51,25 @@ struct Explicit {
 };
 
 
-/* This wants to be a little bit like rust's Cow type.
-   Some parts of the evaluator benefit greatly from being able to reuse
-   existing allocations for strings, but have to be able to also use
-   newly allocated storage for values.
-
-   We do not define implicit conversions, even with ref qualifiers,
-   since those can easily become ambiguous to the reader and can degrade
-   into copying behaviour we want to avoid. */
+/**
+ * This wants to be a little bit like rust's Cow type.
+ * Some parts of the evaluator benefit greatly from being able to reuse
+ * existing allocations for strings, but have to be able to also use
+ * newly allocated storage for values.
+ *
+ * We do not define implicit conversions, even with ref qualifiers,
+ * since those can easily become ambiguous to the reader and can degrade
+ * into copying behaviour we want to avoid.
+ */
 class BackedStringView {
 private:
     std::variant<std::string, std::string_view> data;
 
-    /* Needed to introduce a temporary since operator-> must return
-       a pointer. Without this we'd need to store the view object
-       even when we already own a string. */
+    /**
+     * Needed to introduce a temporary since operator-> must return
+     * a pointer. Without this we'd need to store the view object
+     * even when we already own a string.
+     */
     class Ptr {
     private:
         std::string_view view;
@@ -77,8 +87,10 @@ public:
     BackedStringView(const BackedStringView &) = delete;
     BackedStringView & operator=(const BackedStringView &) = delete;
 
-    /* We only want move operations defined since the sole purpose of
-       this type is to avoid copies. */
+    /**
+     * We only want move operations defined since the sole purpose of
+     * this type is to avoid copies.
+     */
     BackedStringView(BackedStringView && other) = default;
     BackedStringView & operator=(BackedStringView && other) = default;