Some additional docs

(bzr r8846.2.10)

3 files changed, 43 insertions, 20 deletions

diff --git a/src/ui/tool/node.cpp b/src/ui/tool/node.cpp
index adef8e5a7..889f4a793 100644
--- a/src/ui/tool/node.cpp
+++ b/src/ui/tool/node.cpp
@@ -71,7 +71,10 @@ static Geom::Point direction(Geom::Point const &first, Geom::Point const &second
 
 /**
  * @class Handle
- * Represents a control point of a cubic Bezier curve in a path.
+ * @brief Control point of a cubic Bezier curve in a path.
+ *
+ * Handle keeps the node type invariant only for the opposite handle of the same node.
+ * Keeping the invariant on node moves is left to the %Node class.
  */
 
 double Handle::_saved_length = 0.0;
@@ -320,7 +323,9 @@ Glib::ustring Handle::_getDragTip(GdkEventMotion *event)
 
 /**
  * @class Node
- * Represents a curve endpoint in an editable path.
+ * @brief Curve endpoint in an editable path.
+ *
+ * The method move() keeps node type invariants during translations.
  */
 
 Node::Node(NodeSharedData const &data, Geom::Point const &initial_pos)
@@ -554,6 +559,8 @@ void Node::setType(NodeType type, bool update_handles)
     updateState();
 }
 
+/** Pick the best type for this node, based on the position of its handles.
+ * This is what assigns types to nodes created using the pen tool. */
 void Node::pickBestType()
 {
     _type = NODE_CUSP;
@@ -652,7 +659,7 @@ bool Node::_eventHandler(GdkEvent *event)
     return ControlPoint::_eventHandler(event);
 }
 
-// TODO Move this to 2Geom
+// TODO Move this to 2Geom!
 static double bezier_length (Geom::Point a0, Geom::Point a1, Geom::Point a2, Geom::Point a3)
 {
     double lower = Geom::distance(a0, a3);
@@ -844,11 +851,12 @@ void Node::_draggedHandler(Geom::Point &new_pos, GdkEventMotion *event)
     bool snap = sm.someSnapperMightSnap();
     std::vector< std::pair<Geom::Point, int> > unselected;
     if (snap) {
-        // setup
-        // TODO we are doing this every time a snap happens. It should once be done only once
-        //      per drag - maybe in the grabbed handler?
-        // TODO "unselected" must be valid during the snap run, because it is not copied.
-        //      Fix this in snap.h and snap.cpp, then the above.
+        /* setup
+         * TODO We are doing this every time a snap happens. It should once be done only once
+         *      per drag - maybe in the grabbed handler?
+         * TODO Unselected nodes vector must be valid during the snap run, because it is not
+         *      copied. Fix this in snap.h and snap.cpp, then the above.
+         * TODO Snapping to unselected segments of selected paths doesn't work. */
 
         // Build the list of unselected nodes.
         typedef ControlPointSelection::Set Set;
diff --git a/src/ui/tool/node.h b/src/ui/tool/node.h
index a85877d5c..d822d854f 100644
--- a/src/ui/tool/node.h
+++ b/src/ui/tool/node.h
@@ -171,6 +171,28 @@ private:
     friend class NodeIterator<Node const>;
 };
 
+/// Iterator for editable nodes
+/** Use this class for all operations that require some knowledge about the node's
+ * neighbors. It works like a bidirectional iterator.
+ *
+ * Because paths can be cyclic, node iterators have two different ways to
+ * increment and decrement them. Nodes can be iterated over either in the
+ * sequence order, which always has a beginning and an end, or in the path order,
+ * which can be cyclic (moving to the next node never yields the end iterator).
+ *
+ * When @a i is a node iterator, then:
+ * - <code>++i</code> moves the iterator to the next node in sequence order;
+ * - <code>--i</code> moves the iterator to the previous node in sequence order;
+ * - <code>i.next()</code> returns the next node with wrap-around if the path is cyclic;
+ * - <code>i.prev()</code> returns the previous node with wrap-around if the path is cyclic.
+ *
+ * next() and prev() do not change their iterator. They can return the end iterator
+ * if the path is open.
+ *
+ * Unlike most other iterators, you can check whether a node iterator is invalid
+ * (is an end iterator) without having access to the iterator's container.
+ * Simply use <code>if (i) { ...</code>
+ * */
 template <typename N>
 class NodeIterator
     : public boost::bidirectional_iterator_helper<NodeIterator<N>, N, std::ptrdiff_t,
@@ -194,7 +216,9 @@ public:
     bool operator==(self const &other) const { return _node == other._node; }
     N &operator*() const { return *static_cast<N*>(_node); }
     inline operator bool() const; // define after NodeList
+    /// Get a pointer to the underlying node. Equivalent to <code>&*i</code>.
     N *get_pointer() const { return static_cast<N*>(_node); }
+    /// @see get_pointer()
     N *ptr() const { return static_cast<N*>(_node); }
 
     self next() const;
diff --git a/src/ui/tool/transform-handle-set.cpp b/src/ui/tool/transform-handle-set.cpp
index d6181dbf4..cf8907299 100644
--- a/src/ui/tool/transform-handle-set.cpp
+++ b/src/ui/tool/transform-handle-set.cpp
@@ -171,7 +171,7 @@ protected:
 double ScaleHandle::_last_scale_x = 1.0;
 double ScaleHandle::_last_scale_y = 1.0;
 
-/** Corner scaling handle for node transforms */
+/// Corner scaling handle for node transforms
 class ScaleCornerHandle : public ScaleHandle {
 public:
     ScaleCornerHandle(TransformHandleSet &th, unsigned corner)
@@ -225,7 +225,7 @@ private:
     unsigned _corner;
 };
 
-/** Side scaling handle for node transforms */
+/// Side scaling handle for node transforms
 class ScaleSideHandle : public ScaleHandle {
 public:
     ScaleSideHandle(TransformHandleSet &th, unsigned side)
@@ -281,7 +281,7 @@ private:
     unsigned _side;
 };
 
-/** Rotation handle for nodes */
+/// Rotation handle for node transforms
 class RotateHandle : public TransformHandle {
 public:
     RotateHandle(TransformHandleSet &th, unsigned corner)
@@ -339,15 +339,6 @@ private:
         default: return Glib::wrap(handles[4], true);
         }
     }
-    /*
-    static Geom::Point _corner_to_offset_unit(unsigned c) {
-        switch (c % 4) {
-        case 0: return Geom::Point(-1, 1);
-        case 1: return Geom::Point(1, 1);
-        case 2: return Geom::Point(1, -1);
-        default: return Geom::Point(-1, -1);
-        }
-    }*/
     Geom::Point _rot_center;
     Geom::Point _rot_opposite;
     unsigned _corner;