Added some comments.

(bzr r771)

2 files changed, 159 insertions, 3 deletions

diff --git a/src/snap.cpp b/src/snap.cpp
index 3d4a48005..aa3663acf 100644
--- a/src/snap.cpp
+++ b/src/snap.cpp
@@ -21,11 +21,22 @@
 #include <libnr/nr-scale-ops.h>
 #include <libnr/nr-values.h>
 
+/**
+ *  Construct a SnapManager for a SPNamedView.
+ *
+ *  \param v `Owning' SPNamedView.
+ */
+
 SnapManager::SnapManager(SPNamedView const *v) : grid(v, 0), guide(v, 0), object(v, 0)
 {
 
 }
 
+
+/**
+ *  \return List of snappers that we use.
+ */
+
 SnapManager::SnapperList SnapManager::getSnappers() const
 {
     SnapManager::SnapperList s;
@@ -38,6 +49,7 @@ SnapManager::SnapperList SnapManager::getSnappers() const
 /**
  * \return true if one of the snappers will try to snap something.
  */
+
 bool SnapManager::willSnapSomething() const
 {
     SnapperList const s = getSnappers();
@@ -49,6 +61,16 @@ bool SnapManager::willSnapSomething() const
     return (i != s.end());
 }
 
+
+/**
+ *  Try to snap a point to any interested snappers.
+ *
+ *  \param t Type of point.
+ *  \param p Point.
+ *  \param it Item to ignore when snapping.
+ *  \return Snapped point.
+ */
+
 Inkscape::SnappedPoint SnapManager::freeSnap(Inkscape::Snapper::PointType t,
                                              NR::Point const &p,
                                              SPItem const *it) const
@@ -60,6 +82,15 @@ Inkscape::SnappedPoint SnapManager::freeSnap(Inkscape::Snapper::PointType t,
 }
 
 
+/**
+ *  Try to snap a point to any interested snappers.
+ *
+ *  \param t Type of point.
+ *  \param p Point.
+ *  \param it List of items to ignore when snapping.
+ *  \return Snapped point.
+ */
+
 Inkscape::SnappedPoint SnapManager::freeSnap(Inkscape::Snapper::PointType t,
                                              NR::Point const &p,
                                              std::list<SPItem const *> const &it) const
@@ -78,6 +109,17 @@ Inkscape::SnappedPoint SnapManager::freeSnap(Inkscape::Snapper::PointType t,
 }
 
 
+/**
+ *  Try to snap a point to any interested snappers.  A snap will only occur along
+ *  a line described by a Inkscape::Snapper::ConstraintLine.
+ *
+ *  \param t Type of point.
+ *  \param p Point.
+ *  \param c Constraint line.
+ *  \param it Item to ignore when snapping.
+ *  \return Snapped point.
+ */
+
 Inkscape::SnappedPoint SnapManager::constrainedSnap(Inkscape::Snapper::PointType t,
                                                     NR::Point const &p,
                                                     Inkscape::Snapper::ConstraintLine const &c,
@@ -89,6 +131,18 @@ Inkscape::SnappedPoint SnapManager::constrainedSnap(Inkscape::Snapper::PointType
 }
 
 
+
+/**
+ *  Try to snap a point to any interested snappers.  A snap will only occur along
+ *  a line described by a Inkscape::Snapper::ConstraintLine.
+ *
+ *  \param t Type of point.
+ *  \param p Point.
+ *  \param c Constraint line.
+ *  \param it List of items to ignore when snapping.
+ *  \return Snapped point.
+ */
+
 Inkscape::SnappedPoint SnapManager::constrainedSnap(Inkscape::Snapper::PointType t,
                                                     NR::Point const &p,
                                                     Inkscape::Snapper::ConstraintLine const &c,
@@ -108,6 +162,24 @@ Inkscape::SnappedPoint SnapManager::constrainedSnap(Inkscape::Snapper::PointType
 }
 
 
+
+/**
+ *  Main internal snapping method, which is called by the other, friendlier, public
+ *  methods.  It's a bit hairy as it has lots of parameters, but it saves on a lot
+ *  of duplicated code.
+ *
+ *  \param type Type of points being snapped.
+ *  \param points List of points to snap.
+ *  \param ignore List of items to ignore while snapping.
+ *  \param constrained true if the snap is constrained.
+ *  \param constraint Constraint line to use, if `constrained' is true, otherwise undefined.
+ *  \param transformation_type Type of transformation to apply to points before trying to snap them.
+ *  \param transformation Description of the transformation; details depend on the type.
+ *  \param origin Origin of the transformation, if applicable.
+ *  \param dim Dimension of the transformation, if applicable.
+ *  \param uniform true if the transformation should be uniform, if applicable.
+ */
+
 std::pair<NR::Point, bool> SnapManager::_snapTransformed(
     Inkscape::Snapper::PointType type,
     std::vector<NR::Point> const &points,
@@ -224,6 +296,17 @@ std::pair<NR::Point, bool> SnapManager::_snapTransformed(
 }
 
 
+/**
+ *  Try to snap a list of points to any interested snappers after they have undergone
+ *  a translation.
+ *
+ *  \param t Type of points.
+ *  \param p Points.
+ *  \param it List of items to ignore when snapping.
+ *  \param tr Proposed translation.
+ *  \return Snapped translation, if a snap occurred, and a flag indicating whether a snap occurred.
+ */
+
 std::pair<NR::Point, bool> SnapManager::freeSnapTranslation(Inkscape::Snapper::PointType t,
                                                             std::vector<NR::Point> const &p,
                                                             std::list<SPItem const *> const &it,
@@ -235,6 +318,18 @@ std::pair<NR::Point, bool> SnapManager::freeSnapTranslation(Inkscape::Snapper::P
 }
 
 
+/**
+ *  Try to snap a list of points to any interested snappers after they have undergone a
+ *  translation.  A snap will only occur along a line described by a
+ *  Inkscape::Snapper::ConstraintLine.
+ *
+ *  \param t Type of points.
+ *  \param p Points.
+ *  \param it List of items to ignore when snapping.
+ *  \param c Constraint line.
+ *  \param tr Proposed translation.
+ *  \return Snapped translation, if a snap occurred, and a flag indicating whether a snap occurred.
+ */
 
 std::pair<NR::Point, bool> SnapManager::constrainedSnapTranslation(Inkscape::Snapper::PointType t,
                                                                    std::vector<NR::Point> const &p,
@@ -247,6 +342,19 @@ std::pair<NR::Point, bool> SnapManager::constrainedSnapTranslation(Inkscape::Sna
         );
 }
 
+
+/**
+ *  Try to snap a list of points to any interested snappers after they have undergone
+ *  a scale.
+ *
+ *  \param t Type of points.
+ *  \param p Points.
+ *  \param it List of items to ignore when snapping.
+ *  \param s Proposed scale.
+ *  \param o Origin of proposed scale.
+ *  \return Snapped scale, if a snap occurred, and a flag indicating whether a snap occurred.
+ */
+
 std::pair<NR::scale, bool> SnapManager::freeSnapScale(Inkscape::Snapper::PointType t,
                                                       std::vector<NR::Point> const &p,
                                                       std::list<SPItem const *> const &it,
@@ -259,6 +367,19 @@ std::pair<NR::scale, bool> SnapManager::freeSnapScale(Inkscape::Snapper::PointTy
 }
 
 
+/**
+ *  Try to snap a list of points to any interested snappers after they have undergone
+ *  a scale.  A snap will only occur along a line described by a
+ *  Inkscape::Snapper::ConstraintLine.
+ *
+ *  \param t Type of points.
+ *  \param p Points.
+ *  \param it List of items to ignore when snapping.
+ *  \param s Proposed scale.
+ *  \param o Origin of proposed scale.
+ *  \return Snapped scale, if a snap occurred, and a flag indicating whether a snap occurred.
+ */
+
 std::pair<NR::scale, bool> SnapManager::constrainedSnapScale(Inkscape::Snapper::PointType t,
                                                              std::vector<NR::Point> const &p,
                                                              std::list<SPItem const *> const &it,
@@ -272,6 +393,20 @@ std::pair<NR::scale, bool> SnapManager::constrainedSnapScale(Inkscape::Snapper::
 }
 
 
+/**
+ *  Try to snap a list of points to any interested snappers after they have undergone
+ *  a stretch.
+ *
+ *  \param t Type of points.
+ *  \param p Points.
+ *  \param it List of items to ignore when snapping.
+ *  \param s Proposed stretch.
+ *  \param o Origin of proposed stretch.
+ *  \param d Dimension in which to apply proposed stretch.
+ *  \param u true if the stretch should be uniform (ie to be applied equally in both dimensions)
+ *  \return Snapped stretch, if a snap occurred, and a flag indicating whether a snap occurred.
+ */
+
 std::pair<NR::Coord, bool> SnapManager::freeSnapStretch(Inkscape::Snapper::PointType t,
                                                         std::vector<NR::Point> const &p,
                                                         std::list<SPItem const *> const &it,
@@ -288,6 +423,19 @@ std::pair<NR::Coord, bool> SnapManager::freeSnapStretch(Inkscape::Snapper::Point
 }
 
 
+/**
+ *  Try to snap a list of points to any interested snappers after they have undergone
+ *  a skew.
+ *
+ *  \param t Type of points.
+ *  \param p Points.
+ *  \param it List of items to ignore when snapping.
+ *  \param s Proposed skew.
+ *  \param o Origin of proposed skew.
+ *  \param d Dimension in which to apply proposed skew.
+ *  \return Snapped skew, if a snap occurred, and a flag indicating whether a snap occurred.
+ */
+
 std::pair<NR::Coord, bool> SnapManager::freeSnapSkew(Inkscape::Snapper::PointType t,
                                                      std::vector<NR::Point> const &p,
                                                      std::list<SPItem const *> const &it,
diff --git a/src/snap.h b/src/snap.h
index 12996f04d..8345da40d 100644
--- a/src/snap.h
+++ b/src/snap.h
@@ -27,6 +27,14 @@
 
 class SPNamedView;
 
+/// Class to coordinate snapping operations
+
+/**
+ *  Each SPNamedView has one of these.  It offers methods to snap points to whatever
+ *  snappers are defined (e.g. grid, guides etc.).  It also allows callers to snap
+ *  points which have undergone some transformation (e.g. translation, scaling etc.)
+ */
+
 class SnapManager
 {
 public:
@@ -91,9 +99,9 @@ public:
                                             NR::Point const &o,
                                             NR::Dim2 d) const;
 
-    Inkscape::GridSnapper grid;
-    Inkscape::GuideSnapper guide;
-    Inkscape::ObjectSnapper object;
+    Inkscape::GridSnapper grid;     ///< grid snapper
+    Inkscape::GuideSnapper guide;   ///< guide snapper
+    Inkscape::ObjectSnapper object; ///< snapper to other objects
 
     typedef std::list<const Inkscape::Snapper*> SnapperList;
     SnapperList getSnappers() const;