except: add docstrings

except.hpp

@@ -11,6 +11,12 @@
 #include <iosfwd>
 
 namespace cruft {
+    /// A base exception class for all cruft libraries.
+    ///
+    /// There is deliberately no `what` method as it's not always acceptable
+    /// to store a string that we can return a pointer to. Instead we rely on
+    /// the `describe` method to output to a std::ostream. The user can wrangle
+    /// that into a std::string if they need one.
     class error {
     public:
         virtual ~error () = default;
@@ -18,5 +24,8 @@ namespace cruft {
     };
 
 
-    std::ostream& operator<< (std::ostream &os, error const&);
+    /// Use `error::describe` to render the supplied error object to a
+    /// std::ostream.
+    std::ostream&
+    operator<< (std::ostream &os, error const&);
 }