cpp: add some explanatory comments

cpp.hpp

@@ -35,14 +35,22 @@ namespace util::cpp {
 
 
     ///////////////////////////////////////////////////////////////////////////
+    /// an abstract base that performs processing for a directive
     class directive {
     public:
         virtual ~directive () = default;
 
+        /// handles a preprocessor directive by:
+        /// * perform some processing on any number of input lines,
+        /// * optionally writes to the supplied stream,
+        /// * and returns the line that should be consumed next
+        ///
+        /// \param lines is a tokenised view over all the lines of the input
+        /// \return the next line that processing should continue from
         virtual util::tokeniser<const char*>::iterator
         process (std::ostream&,
                  context&,
-                 util::view<util::tokeniser<const char*>::iterator>) const = 0;
+                 util::view<util::tokeniser<const char*>::iterator> lines) const = 0;
     };
 
 
@@ -68,14 +76,18 @@ namespace util::cpp {
 
 
     ///////////////////////////////////////////////////////////////////////////
+    /// thrown when a processor encounters a directive it has not been
+    /// configured to handle
     class unknown_directive : public std::runtime_error {
         using runtime_error::runtime_error;
     };
 
 
     ///////////////////////////////////////////////////////////////////////////
-    class ignore final : public directive {
+    /// silently ignores configured directive by advancing the input cursor
-        virtual util::tokeniser<const char*>::iterator
+    /// past the provided line without writing to the output stream.
+    class ignore : public directive {
+        util::tokeniser<const char*>::iterator
         process (std::ostream&,
                  context&,
                  util::view<util::tokeniser<const char*>::iterator> lines) const override
@@ -83,8 +95,10 @@ namespace util::cpp {
     };
 
 
-    //-------------------------------------------------------------------------
+    ///------------------------------------------------------------------------
-    class passthrough final : public directive {
+    /// copies the supplied directive to the output stream without any
+    /// modification
+    class passthrough : public directive {
     public:
         passthrough (const std::string &name);
 
@@ -98,7 +112,9 @@ namespace util::cpp {
     };
 
 
-    //-------------------------------------------------------------------------
+    ///------------------------------------------------------------------------
+    /// handles include directives by copying the contents of the referenced
+    /// path into the input stream
     class include : public directive {
     public:
         include (processor &_parent);