1 files changed, 61 insertions, 12 deletions

diff --git a/src/xmlcomposehelpers.h b/src/xmlcomposehelpers.h
index f91923e..9d36ef5 100644
--- a/src/xmlcomposehelpers.h
+++ b/src/xmlcomposehelpers.h
@@ -36,6 +36,9 @@
  *
  */
 
+// RENAME: XMLComposeHelpers.h
+// Possibly merge with XMLComposer.h
+
 #ifndef __RTFPARSEHELPERS_H__
 #define __RTFPARSEHELPERS_H__
 
@@ -44,8 +47,15 @@
 #include "sablo.h"
 #include "rtfformatting.h"
 
-class RtfParser;
+class XMLComposer;
 
+/*
+ * Destination
+ *
+ * A destination is a small class that handles the character data found
+ * in the RTF document. Depending on the current context in the RTF
+ * different destinations are used.
+ */
 class Destination :
 	public Instance
 {
@@ -58,11 +68,17 @@ public:
 	virtual void done() {};
 
 protected:
-	RtfParser* m_parser;
-	friend class RtfParser;
+	XMLComposer* m_composer;
+	friend class XMLComposer;
 };
 
-
+/*
+ * Analyser
+ *
+ * An analyser is a small class that handles the RTF control words.
+ * Depending on the current context in the RTF different analysers
+ * are used.
+ */
 class Analyser :
 	public Instance
 {
@@ -79,16 +95,40 @@ public:
 	virtual void done() {};
 
 protected:
-	RtfParser* m_parser;
-	friend class RtfParser;
+	XMLComposer* m_composer;
+	friend class XMLComposer;
 };
 
 class Level;
 
+// Reference counted pointers
 typedef Reference<Destination> DestinationPtr;
 typedef Reference<Analyser> AnalyserPtr;
 typedef Reference<Level> LevelPtr;
 
+/*
+ * Level
+ *
+ * A level is a combination of a Destination, Analyser, XML Element and
+ * some other options. They're used in a stack to push and pop these as
+ * RTF groups are found.
+ *
+ * About the stack:
+ * Not each level has it's own options. If a certain option isn't found
+ * in the current level the previous one is looked up. That's what all
+ * the 'deep' stuff is about below:
+ *
+ * get* methods:
+ * When 'deep' is set look to previous levels for the given object if not
+ * found at the current level. When not set returns object in current level
+ * or null when none exists here.
+ *
+ * set* methods:
+ * When 'deep' is set then replace the object currently being used at it's
+ * own level. So if get* would return an object from a previous level, with
+ * deep set to true it would replace that object in the given level. When
+ * not set, then the object is set in the current level.
+ */
 class Level :
 	public Instance
 {
@@ -99,24 +139,33 @@ public:
 	LevelPtr getPrevious();
 	LevelPtr pushLevel();
 
+    // The current XML Element
+    // TODO: Add deep semantics here
 	DOM::Element getElement();
 	void setElement(DOM::Element element, bool deep = false);
+
+    // The current Analyser
 	AnalyserPtr getAnalyser(bool deep = true);
 	void setAnalyser(AnalyserPtr analyser, bool deep = false);
+
+    // The current Destination
 	DestinationPtr getDestination(bool deep = true);
 	void setDestination(DestinationPtr destination, bool deep = false);
+
+    // The current formatting options
 	RtfFormatting& getFormatting();
 	void setTextProperties(RtfFormatting& textProperties);
 
 protected:
+
+    // Constructor for stacking levels
 	Level(const Level& level);
 
-	LevelPtr m_previous;
-	DOM::Element m_element;
-	RtfFormatting m_text;
-	DestinationPtr m_destination;
-	AnalyserPtr m_analyser;
+	LevelPtr m_previous;           // The previous level
+	DOM::Element m_element;        // XML Element for this level
+	RtfFormatting m_text;          // Formatting options for this level
+	DestinationPtr m_destination;  // Destination for this level
+	AnalyserPtr m_analyser;        // Analyser for this level
 };
 
-
 #endif //__RTFPARSEHELPERS_H__