Add more documentation to printbuffer.h

luprex/cpp/core/printbuffer.hpp

@@ -91,6 +91,27 @@ struct PrintBufferCore;
 
 class PrintBuffer : public eng::nevernew {
 private:
+    // A pointer to a PrintBufferCore that stores the data.
+    //
+    // This pointer can be in two states: it can point
+    // to a heap-allocated PrintBufferCore which is owned,
+    // or it can point to a global variable "empty_core"
+    // which is always empty.  
+    //
+    // Any attempt to write into the printbuffer will
+    // first check if this points to empty_core.  If so,
+    // a PrintBufferCore will be allocated and stored
+    // here, only then will the write happen.
+    //
+    // Clearing the printbuffer will cause any owned
+    // PrintBufferCore to be freed, and the pointer to
+    // empty_core will be restored.
+    //
+    // The advantage of this design is that the empty state
+    // is stored very efficiently, but it's not a null
+    // pointer: it's still a valid core.  You never have
+    // to check for nullptr here.
+    //
     PrintBufferCore *core_;
 
 public: