Add documentation.

docs/textrendering.gv

@@ -0,0 +1,20 @@
+#process with: dot textrendering.gv -Tpng > textrendering.png
+digraph textrendering {
+# Classes without important virtual members: Round
+# Classes with    important virtual members: Rect
+# Pointers [style=dashed]
+# Red: function is called
+  text_placements[shape=box]
+  text_placement_info[shape=box]
+  Renderer
+
+  TextSymbolizer -> text_placements [label="placement_options_", style=dashed]
+  text_placements -> text_symbolizer_properties [label="properties"]
+  text_placements -> text_placement_info [label="get_placement_info()", style=dashed]
+  text_placement_info -> text_symbolizer_properties [label="properties"]
+  text_placement_info -> text_path [label="placements", style=dashed]
+  text_symbolizer_properties -> text_processor [label="processor"]
+  text_path -> Renderer [label="used by"]
+  Renderer -> text_placement_info [color=red, label="init()"]
+  
+}

include/mapnik/text_path.hpp

@@ -117,7 +117,9 @@ public:
     }
 };
     
-struct text_path : boost::noncopyable
+
+/** List of all characters and their positions and formats for a placement. */
+class text_path : boost::noncopyable
 {
     struct character_node
     {
@@ -139,41 +141,51 @@ struct text_path : boost::noncopyable
         }
     };
          
+    int itr_;
+public:
     typedef std::vector<character_node> character_nodes_t;
+    character_nodes_t nodes_;
     double starting_x;
     double starting_y;
-    character_nodes_t nodes_;
-    int itr_;
           
-    std::pair<unsigned,unsigned> string_dimensions;
+//    std::pair<unsigned,unsigned> string_dimensions;
         
     text_path() 
-        : starting_x(0),
+        : itr_(0),
-          starting_y(0),
+          starting_x(0),
-          itr_(0) {} 
+          starting_y(0)
+
+    {
+
+    }
          
     ~text_path() {}
           
+    /** Adds a new char to the list. */
     void add_node(int c, double x, double y, double angle, char_properties *format)
     {
         nodes_.push_back(character_node(c, x, y, angle, format));
     }
         
+    /** Return node. Always returns a new node. Has no way to report that there are no more nodes. */
     void vertex(int *c, double *x, double *y, double *angle, char_properties **format)
     {
         nodes_[itr_++].vertex(c, x, y, angle, format);
     }
          
+    /** Start again at first node. */
     void rewind()
     {
         itr_ = 0;
     }
          
+    /** Number of nodes. */
     int num_nodes() const
     {
         return nodes_.size();
     }
          
+    /** Delete all nodes. */
     void clear()
     {
         nodes_.clear();

include/mapnik/text_placements.hpp

@@ -92,10 +92,13 @@ enum justify_alignment
 
 DEFINE_ENUM( justify_alignment_e, justify_alignment );
 
+/** Contains all text symbolizer properties which are not directly related to text formating. */
 struct text_symbolizer_properties
 {
     text_symbolizer_properties();
+    /** Load all values and also the ```processor``` object from XML ptree. */
     void set_values_from_xml(boost::property_tree::ptree const &sym, std::map<std::string,font_set> const & fontsets);
+    /** Save all values to XML ptree (but does not create a new parent node!). */
     void to_xml(boost::property_tree::ptree &node, bool explicit_defaults, text_symbolizer_properties const &dfl=text_symbolizer_properties()) const;
 
     //Per symbolizer options
@@ -105,71 +108,124 @@ struct text_symbolizer_properties
     horizontal_alignment_e halign;
     justify_alignment_e jalign;
     vertical_alignment_e valign;
-    unsigned label_spacing; // distance between repeated labels on a single geometry
+    /** distance between repeated labels on a single geometry */
-    unsigned label_position_tolerance; //distance the label can be moved on the line to fit, if 0 the default is used
+    unsigned label_spacing;
+    /** distance the label can be moved on the line to fit, if 0 the default is used */
+    unsigned label_position_tolerance;
     bool avoid_edges;
     double minimum_distance;
     double minimum_padding;
     double minimum_path_length;
     double max_char_angle_delta;
-    bool force_odd_labels; //Always try render an odd amount of labels
+    /** Always try render an odd amount of labels */
+    bool force_odd_labels;
     bool allow_overlap;
     unsigned text_ratio;
     unsigned wrap_width;
-    text_processor processor; //Contains expressions and text formats
+    /** Contains everything related to text formating */
+    text_processor processor;
 };
 
+
+/** Generate a possible placement and store results of placement_finder.
+ * This placement has first to be tested by placement_finder to verify it
+ * can actually be used.
+ */
 class text_placement_info : boost::noncopyable
 {
 public:
+    /** Constructor. Takes the parent text_placements object as a parameter
+     * to read defaults from it. */
     text_placement_info(text_placements const* parent);
     /** Get next placement.
       * This function is also called before the first placement is tried.
       * Each class has to return at least one position!
-      * If this functions returns false the placement data should be considered invalid!
+      * If this functions returns false the placement data should be
+      * considered invalid!
       */
     virtual bool next()=0;
     virtual ~text_placement_info() {}
+    /** Initialize values used by placement finder. Only has to be done once
+     * per object.
+     */
     void init(double scale_factor_,
               unsigned w = 0, unsigned h = 0, bool has_dimensions_ = false);
 
+    /** Properties actually used by placement finder and renderer. Values in
+     * here are modified each time next() is called. */
     text_symbolizer_properties properties;
+    
+    /** Scale factor used by the renderer. */
     double scale_factor;
+    /* TODO: Don't know what this is used for. */
     bool has_dimensions;
+    /* TODO: Don't know what this is used for. */
     std::pair<double, double> dimensions;
+    /** Set scale factor. */
     void set_scale_factor(double factor) { scale_factor = factor; }
+    /** Get scale factor. */
     double get_scale_factor() { return scale_factor; }
+    /** Get label spacing taking the scale factor into account. */
     double get_actual_label_spacing() { return scale_factor * properties.label_spacing; }
+    /** Get minimum distance taking the scale factor into account. */
     double get_actual_minimum_distance() { return scale_factor * properties.minimum_distance; }
+     /** Get minimum padding taking the scale factor into account. */
     double get_actual_minimum_padding() { return scale_factor * properties.minimum_padding; }
 
+    /** Collect a bounding box of all texts placed. */
     bool collect_extents;
-    //Output
+    //Output by placement finder
+    /** Bounding box of all texts placed. */
     box2d<double> extents;
+    /* TODO */
     std::queue< box2d<double> > envelopes;
+    /* TODO */
     boost::ptr_vector<placement_element> placements;
 };
 
 typedef boost::shared_ptr<text_placement_info> text_placement_info_ptr;
 
+/** This object handles the management of all TextSymbolizer properties. It can
+ * be used as a base class for own objects which implement new processing 
+ * semantics. Basically this class just makes sure a pointer of the right 
+ * class is returned by the get_placement_info call.
+ */
 class text_placements
 {
 public:
     text_placements();
+    /** Get a text_placement_info object to use in rendering.
+      * The returned object creates a list of settings which is
+      * used to try to find a placement and stores all
+      * information that is generated by
+      * the placement finder. 
+      *
+      * This function usually is implemented as
+      * text_placement_info_ptr text_placements_XXX::get_placement_info() const
+      * {
+      *     return text_placement_info_ptr(new text_placement_info_XXX(this));
+      * }
+      */
     virtual text_placement_info_ptr get_placement_info() const =0;
     /** Get a list of all expressions used in any placement.
       * This function is used to collect attributes.
       */
     virtual std::set<expression_ptr> get_all_expressions();
 
+    /** Destructor. */
     virtual ~text_placements() {}
+    
+    /** List of all properties used as the default for the subclasses. */
     text_symbolizer_properties properties;
 };
 
+/** Pointer to object of class text_placements */
 typedef boost::shared_ptr<text_placements> text_placements_ptr;
 
+
 class text_placements_info_dummy;
 
+/** Dummy placement algorithm. Always takes the default value. */
 class MAPNIK_DECL text_placements_dummy: public text_placements
 {
 public:
@@ -177,6 +233,7 @@ public:
     friend class text_placement_info_dummy;
 };
 
+/** Placement info object for dummy placement algorithm. Always takes the default value. */
 class MAPNIK_DECL text_placement_info_dummy : public text_placement_info
 {
 public:

include/mapnik/text_processing.hpp

@@ -68,9 +68,6 @@ struct char_properties
     double halo_radius;
 };
 
-class abstract_token;
-class processed_text;
-
 class processed_expression
 {
 public:
@@ -78,8 +75,7 @@ public:
         p(properties), str(text) {}
     char_properties p;
     UnicodeString str;
-private:
+
-    friend class processed_text;
 };
 
 class processed_text
@@ -101,15 +97,24 @@ private:
     string_info info_;
 };
 
+class abstract_token;
 
+/** Stores formating information and uses this to produce formated text for a given feature. */
 class text_processor
 {
 public:
     text_processor();
+    /** Construct object from XML. */
     void from_xml(boost::property_tree::ptree const& pt, std::map<std::string,font_set> const &fontsets);
+    /** Write object to XML ptree. */
     void to_xml(boost::property_tree::ptree &node,  bool explicit_defaults, text_processor const& dfl) const;
+    
+    /** Takes a feature and produces formated text as output. 
+     * The output object has to be created by the caller and passed in for thread safety.
+     */
     void process(processed_text &output, Feature const& feature);
     void set_old_style_expression(expression_ptr expr);
+    /** Add a new formating token. */
     void push_back(abstract_token *token);
     std::set<expression_ptr> get_all_expressions() const;
     char_properties defaults;