singleton: add comments

singleton.hpp

@@ -23,6 +23,11 @@
 
 
 namespace util {
+    /// statically stores a single value of the named type.
+    ///
+    /// this does not prevent the instantiation of the named type, but
+    /// instead defines a method to refer to a single instance across an
+    /// application.
     template <typename SelfT>
     class singleton {
     private:
@@ -31,6 +36,15 @@ namespace util {
         static SelfT *instance;
 
     public:
+        /// instantiates the one blessed value of this type.
+        ///
+        /// `instantiate` must be called once and once only before any calls
+        /// to `get`. it is not threadsafe. there are some (unsafe)
+        /// assertions against multiple instantiations but they may not be
+        /// relied upon.
+        ///
+        /// returns a unique_ptr to the value which the caller must store
+        /// until it will never be needed again.
         template <typename ...Args>
         static std::unique_ptr<SelfT>
         instantiate [[nodiscard]] (Args &&...args)
@@ -43,9 +57,13 @@ namespace util {
         }
 
 
+        /// returns a reference to sole instantiated value
+        ///
+        /// `instantiate` must have already been called before `get` is called.
         static SelfT&
         get (void)
         {
+            CHECK (instance);
             return *instance;
         }
     };