Fixing more broken and split doc comments.

(bzr r10697)

157 files changed, 2071 insertions, 1943 deletions

diff --git a/src/2geom/sbasis-geometric.cpp b/src/2geom/sbasis-geometric.cpp
index 7d7ed23e4..1c180e143 100644
--- a/src/2geom/sbasis-geometric.cpp
+++ b/src/2geom/sbasis-geometric.cpp
@@ -4,7 +4,8 @@
 //#include <2geom/solver.h>
 #include <2geom/sbasis-geometric.h>
 
-/** Geometric operators on D2<SBasis> (1D->2D).
+/*
+ * Geometric operators on D2<SBasis> (1D->2D).
  * Copyright 2007 JF Barraud
  * Copyright 2007 N Hurst
  *
diff --git a/src/2geom/sbasis-roots.cpp b/src/2geom/sbasis-roots.cpp
index 1b870d88f..4602fced9 100644
--- a/src/2geom/sbasis-roots.cpp
+++ b/src/2geom/sbasis-roots.cpp
@@ -1,4 +1,5 @@
-/** root finding for sbasis functions.
+/*
+ * root finding for sbasis functions.
  * Copyright 2006 N Hurst
  * Copyright 2007 JF Barraud
  *
diff --git a/src/2geom/shape.cpp b/src/2geom/shape.cpp
index e9f5e55dc..c389b9c6e 100644
--- a/src/2geom/shape.cpp
+++ b/src/2geom/shape.cpp
@@ -1,5 +1,5 @@
-/**
- * \brief  Shapes are special paths on which boolops can be performed
+/*
+ * Shapes are special paths on which boolops can be performed.
  *
  * Authors:
  *      Michael G. Sloan <mgsloan@gmail.com>
diff --git a/src/2geom/svg-path-parser.cpp b/src/2geom/svg-path-parser.cpp
index 4d35ccb35..24f9c81ee 100644
--- a/src/2geom/svg-path-parser.cpp
+++ b/src/2geom/svg-path-parser.cpp
@@ -1,7 +1,6 @@
 #line 1 "/opt/shared/work/programming/eclipse/eclipse_3.4/lib2geom/src/2geom/svg-path-parser.rl"
-/**
- * \file
- * \brief parse SVG path specifications
+/*
+ * parse SVG path specifications.
  *
  * Copyright 2007 MenTaLguY <mental@rydia.net>
  * Copyright 2007 Aaron Spike <aaron@ekips.org>
diff --git a/src/2geom/utils.cpp b/src/2geom/utils.cpp
index a40b7253d..4c9629deb 100644
--- a/src/2geom/utils.cpp
+++ b/src/2geom/utils.cpp
@@ -1,4 +1,5 @@
-/** Various utility functions.
+/*
+ * Various utility functions.
  *
  * Copyright 2008 Marco Cecchetti <mrcekets at gmail.com>
  * Copyright 2007 Johan Engelen <goejendaagh@zonnet.nl>
diff --git a/src/bind/dobinding.cpp b/src/bind/dobinding.cpp
index 284565e92..5e783e59d 100644
--- a/src/bind/dobinding.cpp
+++ b/src/bind/dobinding.cpp
@@ -1,5 +1,4 @@
-/**
- * @file
+/*
  * This is a simple mechanism to bind Inkscape to Java, and thence
  * to all of the nice things that can be layered upon that.
  *
diff --git a/src/color.cpp b/src/color.cpp
index 54af89ae5..ab01ebc2a 100644
--- a/src/color.cpp
+++ b/src/color.cpp
@@ -1,6 +1,4 @@
-#define __SP_COLOR_C__
-
-/** \file
+/*
  * Colors.
  *
  * Author:
diff --git a/src/connector-context.cpp b/src/connector-context.cpp
index ecc8cdaad..b2687e540 100644
--- a/src/connector-context.cpp
+++ b/src/connector-context.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Connector creation tool
  *
  * Authors:
diff --git a/src/deptool.cpp b/src/deptool.cpp
index 45a01c4e7..7233c5544 100644
--- a/src/deptool.cpp
+++ b/src/deptool.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * DepTool dependency tool
  *
  * This is a simple dependency generator coded in C++
diff --git a/src/desktop-style.cpp b/src/desktop-style.cpp
index 074e7bf67..b29799bb3 100644
--- a/src/desktop-style.cpp
+++ b/src/desktop-style.cpp
@@ -1,4 +1,4 @@
-/** \file
+/*
  * Desktop style management
  *
  * Authors:
diff --git a/src/desktop.cpp b/src/desktop.cpp
index 2bec9afec..de6b3cafe 100644
--- a/src/desktop.cpp
+++ b/src/desktop.cpp
@@ -1,4 +1,4 @@
-/** \file
+/*
  * Editable view implementation
  *
  * Authors:
@@ -21,33 +21,6 @@
  * Released under GNU GPL, read the file 'COPYING' for more information
  */
 
-/** \class SPDesktop
- * SPDesktop is a subclass of View, implementing an editable document
- * canvas.  It is extensively used by many UI controls that need certain
- * visual representations of their own.
- *
- * SPDesktop provides a certain set of SPCanvasItems, serving as GUI
- * layers of different control objects. The one containing the whole
- * document is the drawing layer. In addition to it, there are grid,
- * guide, sketch and control layers. The sketch layer is used for
- * temporary drawing objects, before the real objects in document are
- * created. The control layer contains editing knots, rubberband and
- * similar non-document UI objects.
- *
- * Each SPDesktop is associated with a SPNamedView node of the document
- * tree.  Currently, all desktops are created from a single main named
- * view, but in the future there may be support for different ones.
- * SPNamedView serves as an in-document container for desktop-related
- * data, like grid and guideline placement, snapping options and so on.
- *
- * Associated with each SPDesktop are the two most important editing
- * related objects - SPSelection and SPEventContext.
- *
- * Sodipodi keeps track of the active desktop and invokes notification
- * signals whenever it changes. UI elements can use these to update their
- * display to the selection of the currently active editing window.
- * (Lauris Kaplinski)
- */
 
 #ifdef HAVE_CONFIG_H
 # include "config.h"
@@ -116,11 +89,6 @@ static void _reconstruction_start(SPDesktop * desktop);
 static void _reconstruction_finish(SPDesktop * desktop);
 static void _namedview_modified (SPObject *obj, guint flags, SPDesktop *desktop);
 
-/**
- * Return new desktop object.
- * \pre namedview != NULL.
- * \pre canvas != NULL.
- */
 SPDesktop::SPDesktop() :
     _dlg_mgr( 0 ),
     namedview( 0 ),
diff --git a/src/desktop.h b/src/desktop.h
index 25e4387dc..8921f45b8 100644
--- a/src/desktop.h
+++ b/src/desktop.h
@@ -82,7 +82,31 @@ namespace Inkscape {
 }
 
 /**
- * Editable view.
+ * SPDesktop is a subclass of View, implementing an editable document
+ * canvas.  It is extensively used by many UI controls that need certain
+ * visual representations of their own.
+ *
+ * SPDesktop provides a certain set of SPCanvasItems, serving as GUI
+ * layers of different control objects. The one containing the whole
+ * document is the drawing layer. In addition to it, there are grid,
+ * guide, sketch and control layers. The sketch layer is used for
+ * temporary drawing objects, before the real objects in document are
+ * created. The control layer contains editing knots, rubberband and
+ * similar non-document UI objects.
+ *
+ * Each SPDesktop is associated with a SPNamedView node of the document
+ * tree.  Currently, all desktops are created from a single main named
+ * view, but in the future there may be support for different ones.
+ * SPNamedView serves as an in-document container for desktop-related
+ * data, like grid and guideline placement, snapping options and so on.
+ *
+ * Associated with each SPDesktop are the two most important editing
+ * related objects - SPSelection and SPEventContext.
+ *
+ * Sodipodi keeps track of the active desktop and invokes notification
+ * signals whenever it changes. UI elements can use these to update their
+ * display to the selection of the currently active editing window.
+ * (Lauris Kaplinski)
  *
  * @see \ref desktop-handles.h for desktop macros.
  */
@@ -185,7 +209,13 @@ public:
     Inkscape::Whiteboard::SessionManager* _whiteboard_session_manager;
 #endif
 
+    /**
+     * Return new desktop object.
+     * \pre namedview != NULL.
+     * \pre canvas != NULL.
+     */
     SPDesktop();
+
     void init (SPNamedView* nv, SPCanvas* canvas, Inkscape::UI::View::EditWidgetInterface *widget);
     virtual ~SPDesktop();
     void destroy();
diff --git a/src/display/canvas-temporary-item-list.cpp b/src/display/canvas-temporary-item-list.cpp
index c324a5ddf..b0fec98b5 100644
--- a/src/display/canvas-temporary-item-list.cpp
+++ b/src/display/canvas-temporary-item-list.cpp
@@ -1,4 +1,4 @@
-/** \file
+/*
  * Provides a class that can contain active TemporaryItem's on a desktop
  * Code inspired by message-stack.cpp
  *
diff --git a/src/display/canvas-temporary-item.cpp b/src/display/canvas-temporary-item.cpp
index 8d336f0ff..abe5f2f1b 100644
--- a/src/display/canvas-temporary-item.cpp
+++ b/src/display/canvas-temporary-item.cpp
@@ -1,4 +1,4 @@
-/** \file
+/*
  * Provides a class that can contain active TemporaryItem's on a desktop
  * When the object is deleted, it also deletes the canvasitem it contains!
  * This object should be created/managed by a TemporaryItemList.
diff --git a/src/display/snap-indicator.cpp b/src/display/snap-indicator.cpp
index e542d0c88..9b61d4a4d 100644
--- a/src/display/snap-indicator.cpp
+++ b/src/display/snap-indicator.cpp
@@ -1,4 +1,4 @@
-/** \file
+/*
  * Provides a class that shows a temporary indicator on the canvas of where the snap was, and what kind of snap
  *
  * Authors:
diff --git a/src/display/sp-canvas.cpp b/src/display/sp-canvas.cpp
index 9e942ec35..8aa3b2a6d 100644
--- a/src/display/sp-canvas.cpp
+++ b/src/display/sp-canvas.cpp
@@ -1,4 +1,4 @@
-/** \file
+/*
  * Port of GnomeCanvas for Inkscape needs
  *
  * Authors:
diff --git a/src/document-undo.cpp b/src/document-undo.cpp
index 1559dc5ba..61c78fe8a 100644
--- a/src/document-undo.cpp
+++ b/src/document-undo.cpp
@@ -1,4 +1,4 @@
-/** \file
+/*
  * Undo/Redo stack implementation
  *
  * Authors:
diff --git a/src/document.cpp b/src/document.cpp
index d45041296..6035ea557 100644
--- a/src/document.cpp
+++ b/src/document.cpp
@@ -1,4 +1,4 @@
-/** \file
+/*
  * SPDocument manipulation
  *
  * Authors:
diff --git a/src/dom/cssreader.cpp b/src/dom/cssreader.cpp
index 4e329d914..db114ed8d 100644
--- a/src/dom/cssreader.cpp
+++ b/src/dom/cssreader.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Phoebe DOM Implementation.
  *
  * This is a C++ approximation of the W3C DOM model, which follows
diff --git a/src/dom/domimpl.cpp b/src/dom/domimpl.cpp
index e12f40714..53118b1d9 100644
--- a/src/dom/domimpl.cpp
+++ b/src/dom/domimpl.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Phoebe DOM Implementation.
  *
  * This is a C++ approximation of the W3C DOM model, which follows
diff --git a/src/dom/domptr.cpp b/src/dom/domptr.cpp
index 107f05b08..73999e100 100644
--- a/src/dom/domptr.cpp
+++ b/src/dom/domptr.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Phoebe DOM Implementation.
  *
  * This is a C++ approximation of the W3C DOM model, which follows
diff --git a/src/dom/domstring.cpp b/src/dom/domstring.cpp
index e562f079f..32e3c078f 100644
--- a/src/dom/domstring.cpp
+++ b/src/dom/domstring.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Phoebe DOM Implementation.
  *
  * This is a C++ approximation of the W3C DOM model, which follows
diff --git a/src/dom/io/base64stream.cpp b/src/dom/io/base64stream.cpp
index 509c67d6d..433675e18 100644
--- a/src/dom/io/base64stream.cpp
+++ b/src/dom/io/base64stream.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Phoebe DOM Implementation.
  *
  * Base64-enabled input and output streams
diff --git a/src/dom/io/bufferstream.cpp b/src/dom/io/bufferstream.cpp
index 6c3956a60..7baab4814 100644
--- a/src/dom/io/bufferstream.cpp
+++ b/src/dom/io/bufferstream.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Phoebe DOM Implementation.
  *
  * This is a C++ approximation of the W3C DOM model, which follows
diff --git a/src/dom/io/domstream.cpp b/src/dom/io/domstream.cpp
index b38dd5329..de221f855 100644
--- a/src/dom/io/domstream.cpp
+++ b/src/dom/io/domstream.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Phoebe DOM Implementation.
  *
  * This is a C++ approximation of the W3C DOM model, which follows
diff --git a/src/dom/io/gzipstream.cpp b/src/dom/io/gzipstream.cpp
index 9dffceea2..e1f9f9a60 100644
--- a/src/dom/io/gzipstream.cpp
+++ b/src/dom/io/gzipstream.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Zlib-enabled input and output streams
  *
  * This is a thin wrapper of libz calls, in order
diff --git a/src/dom/io/stringstream.cpp b/src/dom/io/stringstream.cpp
index f2745a107..c6e47045e 100644
--- a/src/dom/io/stringstream.cpp
+++ b/src/dom/io/stringstream.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Phoebe DOM Implementation.
  *
  * This is a C++ approximation of the W3C DOM model, which follows
diff --git a/src/dom/io/uristream.cpp b/src/dom/io/uristream.cpp
index 306f7bdf6..09b0ac361 100644
--- a/src/dom/io/uristream.cpp
+++ b/src/dom/io/uristream.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Phoebe DOM Implementation.
  *
  * This is a C++ approximation of the W3C DOM model, which follows
diff --git a/src/dom/lsimpl.cpp b/src/dom/lsimpl.cpp
index 6ee6d0883..94b0adeb7 100644
--- a/src/dom/lsimpl.cpp
+++ b/src/dom/lsimpl.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Phoebe DOM Implementation.
  *
  * This is a C++ approximation of the W3C DOM model, which follows
diff --git a/src/dom/odf/odfdocument.cpp b/src/dom/odf/odfdocument.cpp
index c3bb5d97d..50af90f6c 100644
--- a/src/dom/odf/odfdocument.cpp
+++ b/src/dom/odf/odfdocument.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  *
  * This class contains an ODF Document.
  * Initially, we are just concerned with .odg content.xml + resources
diff --git a/src/dom/prop-css.cpp b/src/dom/prop-css.cpp
index 5ef25ce49..a0d66d939 100644
--- a/src/dom/prop-css.cpp
+++ b/src/dom/prop-css.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Phoebe DOM Implementation.
  *
  * This is a C++ approximation of the W3C DOM model, which follows
diff --git a/src/dom/prop-css2.cpp b/src/dom/prop-css2.cpp
index b02bb0ce3..33548fbb9 100644
--- a/src/dom/prop-css2.cpp
+++ b/src/dom/prop-css2.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Phoebe DOM Implementation.
  *
  * This is a C++ approximation of the W3C DOM model, which follows
diff --git a/src/dom/prop-svg.cpp b/src/dom/prop-svg.cpp
index a38f23c23..bcb8dffea 100644
--- a/src/dom/prop-svg.cpp
+++ b/src/dom/prop-svg.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Phoebe DOM Implementation.
  *
  * This is a C++ approximation of the W3C DOM model, which follows
diff --git a/src/dom/smilimpl.cpp b/src/dom/smilimpl.cpp
index 82bbe9d0e..94726ee61 100644
--- a/src/dom/smilimpl.cpp
+++ b/src/dom/smilimpl.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Phoebe DOM Implementation.
  *
  * This is a C++ approximation of the W3C DOM model, which follows
diff --git a/src/dom/svgimpl.cpp b/src/dom/svgimpl.cpp
index b6fbb89e5..cf28dfec5 100644
--- a/src/dom/svgimpl.cpp
+++ b/src/dom/svgimpl.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Phoebe DOM Implementation.
  *
  * This is a C++ approximation of the W3C DOM model, which follows
diff --git a/src/dom/svgreader.cpp b/src/dom/svgreader.cpp
index 4584ba32f..932fcec58 100644
--- a/src/dom/svgreader.cpp
+++ b/src/dom/svgreader.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Phoebe DOM Implementation.
  *
  * This is a C++ approximation of the W3C DOM model, which follows
diff --git a/src/dom/uri.cpp b/src/dom/uri.cpp
index 6a34f1838..d559dffeb 100644
--- a/src/dom/uri.cpp
+++ b/src/dom/uri.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Phoebe DOM Implementation.
  *
  * This is a C++ approximation of the W3C DOM model, which follows
diff --git a/src/dom/util/digest.cpp b/src/dom/util/digest.cpp
index f416f5522..2baed4860 100644
--- a/src/dom/util/digest.cpp
+++ b/src/dom/util/digest.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Secure Hashing Tool
  * *
  * Authors:
diff --git a/src/dom/util/thread.cpp b/src/dom/util/thread.cpp
index 3bb614b45..e8c06c850 100644
--- a/src/dom/util/thread.cpp
+++ b/src/dom/util/thread.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Phoebe DOM Implementation.
  *
  * This is a C++ approximation of the W3C DOM model, which follows
diff --git a/src/dom/util/ziptool.cpp b/src/dom/util/ziptool.cpp
index 89e85cc84..0b13f66ba 100644
--- a/src/dom/util/ziptool.cpp
+++ b/src/dom/util/ziptool.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * This is intended to be a standalone, reduced capability
  * implementation of Gzip and Zip functionality.  Its
  * targeted use case is for archiving and retrieving single files
diff --git a/src/dom/xmlreader.cpp b/src/dom/xmlreader.cpp
index fc4eee51f..501da6193 100644
--- a/src/dom/xmlreader.cpp
+++ b/src/dom/xmlreader.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Phoebe DOM Implementation.
  *
  * This is a C++ approximation of the W3C DOM model, which follows
diff --git a/src/dom/xmlwriter.cpp b/src/dom/xmlwriter.cpp
index 2b056cf9f..a25dbe0b1 100644
--- a/src/dom/xmlwriter.cpp
+++ b/src/dom/xmlwriter.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Phoebe DOM Implementation.
  *
  * This is a C++ approximation of the W3C DOM model, which follows
diff --git a/src/dom/xpathimpl.cpp b/src/dom/xpathimpl.cpp
index b7aa2c1c8..12e1d8cf4 100644
--- a/src/dom/xpathimpl.cpp
+++ b/src/dom/xpathimpl.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Phoebe DOM Implementation.
  *
  * This is a C++ approximation of the W3C DOM model, which follows
diff --git a/src/dom/xpathparser.cpp b/src/dom/xpathparser.cpp
index bbe0fcc40..5fd31c12a 100644
--- a/src/dom/xpathparser.cpp
+++ b/src/dom/xpathparser.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Phoebe DOM Implementation.
  *
  * This is a C++ approximation of the W3C DOM model, which follows
diff --git a/src/dom/xpathtoken.cpp b/src/dom/xpathtoken.cpp
index 921cbf044..79948e55e 100644
--- a/src/dom/xpathtoken.cpp
+++ b/src/dom/xpathtoken.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Phoebe DOM Implementation.
  *
  * This is a C++ approximation of the W3C DOM model, which follows
diff --git a/src/event-context.cpp b/src/event-context.cpp
index a92ab55e2..4f938bde5 100644
--- a/src/event-context.cpp
+++ b/src/event-context.cpp
@@ -1,5 +1,4 @@
-/**
- * @file
+/*
  * Main event handling, and related helper functions.
  *
  * Authors:
diff --git a/src/extension/internal/odf.cpp b/src/extension/internal/odf.cpp
index 2c6a1a80b..3e0afdd8e 100644
--- a/src/extension/internal/odf.cpp
+++ b/src/extension/internal/odf.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * OpenDocument <drawing> input and output
  *
  * This is an an entry in the extensions mechanism to begin to enable
diff --git a/src/extension/internal/pdfinput/pdf-input.cpp b/src/extension/internal/pdfinput/pdf-input.cpp
index 186f337c4..e083fe1a3 100644
--- a/src/extension/internal/pdfinput/pdf-input.cpp
+++ b/src/extension/internal/pdfinput/pdf-input.cpp
@@ -1,4 +1,4 @@
- /** \file
+/*
  * Native PDF import using libpoppler.
  *
  * Authors:
diff --git a/src/extension/internal/pdfinput/pdf-parser.cpp b/src/extension/internal/pdfinput/pdf-parser.cpp
index ef31cd39f..db7c09575 100644
--- a/src/extension/internal/pdfinput/pdf-parser.cpp
+++ b/src/extension/internal/pdfinput/pdf-parser.cpp
@@ -1,6 +1,5 @@
-
- /** \file
- * PDF parsing using libpoppler
+ /*
+ * PDF parsing using libpoppler.
  *
  * Derived from poppler's Gfx.cc
  *
diff --git a/src/extension/internal/pdfinput/svg-builder.cpp b/src/extension/internal/pdfinput/svg-builder.cpp
index be60493e0..64cb0a152 100644
--- a/src/extension/internal/pdfinput/svg-builder.cpp
+++ b/src/extension/internal/pdfinput/svg-builder.cpp
@@ -1,4 +1,4 @@
- /** \file
+ /*
  * Native PDF import using libpoppler.
  * 
  * Authors:
diff --git a/src/extension/script/InkscapeScript.cpp b/src/extension/script/InkscapeScript.cpp
index ec9b5a8f9..9f8ebfbbb 100644
--- a/src/extension/script/InkscapeScript.cpp
+++ b/src/extension/script/InkscapeScript.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * This is a simple mechanism to bind Inkscape to Java, and thence
  * to all of the nice things that can be layered upon that.
  *
diff --git a/src/guide-snapper.cpp b/src/guide-snapper.cpp
index f772aad96..d6741b642 100644
--- a/src/guide-snapper.cpp
+++ b/src/guide-snapper.cpp
@@ -1,5 +1,4 @@
-/**
- *  @file guide-snapper.cpp
+/*
  *  Snapping things to guides.
  *
  * Authors:
diff --git a/src/helper/action.cpp b/src/helper/action.cpp
index 48ba7f2ea..4fafa191e 100644
--- a/src/helper/action.cpp
+++ b/src/helper/action.cpp
@@ -1,5 +1,4 @@
-/**
- * @file
+/*
  * SPAction implementation.
  *
  * Author:
diff --git a/src/helper/geom-nodetype.cpp b/src/helper/geom-nodetype.cpp
index f570fc9ae..605eaaa5f 100644
--- a/src/helper/geom-nodetype.cpp
+++ b/src/helper/geom-nodetype.cpp
@@ -1,6 +1,6 @@
 #define INKSCAPE_HELPER_GEOM_NODETYPE_CPP
 
-/**
+/*
  * Specific nodetype geometry functions for Inkscape, not provided my lib2geom.
  *
  * Author:
diff --git a/src/helper/geom.cpp b/src/helper/geom.cpp
index 61551ad2e..c0e4870d4 100644
--- a/src/helper/geom.cpp
+++ b/src/helper/geom.cpp
@@ -1,6 +1,6 @@
 #define INKSCAPE_HELPER_GEOM_CPP
 
-/**
+/*
  * Specific geometry functions for Inkscape, not provided my lib2geom.
  *
  * Author:
diff --git a/src/id-clash.cpp b/src/id-clash.cpp
index d5740c0ba..e5a40868b 100644
--- a/src/id-clash.cpp
+++ b/src/id-clash.cpp
@@ -1,4 +1,4 @@
-/** \file
+/*
  * Routines for resolving ID clashes when importing or pasting.
  *
  * Authors:
diff --git a/src/io/base64stream.cpp b/src/io/base64stream.cpp
index c90f3760b..0b20ef95a 100644
--- a/src/io/base64stream.cpp
+++ b/src/io/base64stream.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Base64-enabled input and output streams
  *
  * This class allows easy encoding and decoding
diff --git a/src/io/gzipstream.cpp b/src/io/gzipstream.cpp
index 79bcb2087..ed94974fe 100644
--- a/src/io/gzipstream.cpp
+++ b/src/io/gzipstream.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Zlib-enabled input and output streams
  *
  * This is a thin wrapper of libz calls, in order
diff --git a/src/io/inkscapestream.cpp b/src/io/inkscapestream.cpp
index c89dd70fc..da7870add 100644
--- a/src/io/inkscapestream.cpp
+++ b/src/io/inkscapestream.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Our base input/output stream classes.  These are is directly
  * inherited from iostreams, and includes any extra
  * functionality that we might need.
diff --git a/src/io/resource.cpp b/src/io/resource.cpp
index 8c76c7132..4eeaf3b8c 100644
--- a/src/io/resource.cpp
+++ b/src/io/resource.cpp
@@ -1,4 +1,4 @@
-/** \file
+/*
  * Inkscape::IO::Resource - simple resource API
  *
  * Copyright 2006 MenTaLguY <mental@rydia.net>
diff --git a/src/io/stringstream.cpp b/src/io/stringstream.cpp
index 45fb6fe30..44d11dd04 100644
--- a/src/io/stringstream.cpp
+++ b/src/io/stringstream.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Our base String stream classes.  We implement these to
  * be based on Glib::ustring
  *
diff --git a/src/io/uristream.cpp b/src/io/uristream.cpp
index b5f884b29..7397d725f 100644
--- a/src/io/uristream.cpp
+++ b/src/io/uristream.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Our base String stream classes.  We implement these to
  * be based on Glib::ustring
  *
diff --git a/src/io/xsltstream.cpp b/src/io/xsltstream.cpp
index 6f35d9cb6..6b72627d3 100644
--- a/src/io/xsltstream.cpp
+++ b/src/io/xsltstream.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * XSL Transforming input and output classes
  *
  * Authors:
diff --git a/src/io/xsltstream.h b/src/io/xsltstream.h
index 03621c7fd..cfe9e5124 100644
--- a/src/io/xsltstream.h
+++ b/src/io/xsltstream.h
@@ -2,7 +2,7 @@
 #define SEEN_INKSCAPE_IO_XSLTSTREAM_H
 /**
  * @file
- * Xslt-enabled input and output streams
+ * Xslt-enabled input and output streams.
  */
 /*
  * Authors:
diff --git a/src/knot-holder-entity.cpp b/src/knot-holder-entity.cpp
index 835ce7550..c556195d6 100644
--- a/src/knot-holder-entity.cpp
+++ b/src/knot-holder-entity.cpp
@@ -1,4 +1,4 @@
-/** \file
+/*
  * KnotHolderEntity definition.
  *
  * Authors:
diff --git a/src/knot.cpp b/src/knot.cpp
index 1ffb5269c..4dfccc18a 100644
--- a/src/knot.cpp
+++ b/src/knot.cpp
@@ -1,4 +1,4 @@
-/** \file
+/*
  * SPKnot implementation
  *
  * Authors:
@@ -68,9 +68,6 @@ static void sp_knot_set_ctrl_state(SPKnot *knot);
 static GObjectClass *parent_class;
 static guint knot_signals[LAST_SIGNAL] = { 0 };
 
-/**
- * Registers SPKnot class and returns its type number.
- */
 GType sp_knot_get_type()
 {
     static GType type = 0;
@@ -258,9 +255,6 @@ static void sp_knot_dispose(GObject *object)
     }
 }
 
-/**
- * Update knot for dragging and tell canvas an item was grabbed.
- */
 void sp_knot_start_dragging(SPKnot *knot, Geom::Point const &p, gint x, gint y, guint32 etime)
 {
     // save drag origin
@@ -463,9 +457,6 @@ void sp_knot_handler_request_position(GdkEvent *event, SPKnot *knot)
         gobble_motion_events(GDK_BUTTON1_MASK);
 }
 
-/**
- * Return new knot object.
- */
 SPKnot *sp_knot_new(SPDesktop *desktop, const gchar *tip)
 {
     g_return_val_if_fail(desktop != NULL, NULL);
@@ -495,9 +486,6 @@ SPKnot *sp_knot_new(SPDesktop *desktop, const gchar *tip)
     return knot;
 }
 
-/**
- * Show knot on its canvas.
- */
 void sp_knot_show(SPKnot *knot)
 {
     g_return_if_fail(knot != NULL);
@@ -506,9 +494,6 @@ void sp_knot_show(SPKnot *knot)
     sp_knot_set_flag(knot, SP_KNOT_VISIBLE, TRUE);
 }
 
-/**
- * Hide knot on its canvas.
- */
 void sp_knot_hide(SPKnot *knot)
 {
     g_return_if_fail(knot != NULL);
@@ -517,9 +502,6 @@ void sp_knot_hide(SPKnot *knot)
     sp_knot_set_flag(knot, SP_KNOT_VISIBLE, FALSE);
 }
 
-/**
- * Request or set new position for knot.
- */
 void sp_knot_request_position(SPKnot *knot, Geom::Point const &p, guint state)
 {
     g_return_if_fail(knot != NULL);
@@ -540,9 +522,6 @@ void sp_knot_request_position(SPKnot *knot, Geom::Point const &p, guint state)
     }
 }
 
-/**
- * Return distance of point to knot's position; unused.
- */
 gdouble sp_knot_distance(SPKnot * knot, Geom::Point const &p, guint state)
 {
     g_return_val_if_fail(knot != NULL, 1e18);
@@ -559,9 +538,6 @@ gdouble sp_knot_distance(SPKnot * knot, Geom::Point const &p, guint state)
     return distance;
 }
 
-/**
- * Move knot to new position.
- */
 void sp_knot_set_position(SPKnot *knot, Geom::Point const &p, guint state)
 {
     g_return_if_fail(knot != NULL);
@@ -580,9 +556,6 @@ void sp_knot_set_position(SPKnot *knot, Geom::Point const &p, guint state)
     knot->_moved_signal.emit(knot, p, state);
 }
 
-/**
- * Move knot to new position, without emitting a MOVED signal.
- */
 void sp_knot_moveto(SPKnot *knot, Geom::Point const &p)
 {
     g_return_if_fail(knot != NULL);
@@ -595,9 +568,6 @@ void sp_knot_moveto(SPKnot *knot, Geom::Point const &p)
     }
 }
 
-/**
- * Returns position of knot.
- */
 Geom::Point sp_knot_position(SPKnot const *knot)
 {
     g_assert(knot != NULL);
@@ -606,9 +576,6 @@ Geom::Point sp_knot_position(SPKnot const *knot)
     return knot->pos;
 }
 
-/**
- * Set flag in knot, with side effects.
- */
 void sp_knot_set_flag(SPKnot *knot, guint flag, bool set)
 {
     g_assert(knot != NULL);
@@ -640,9 +607,6 @@ void sp_knot_set_flag(SPKnot *knot, guint flag, bool set)
     }
 }
 
-/**
- * Update knot's pixbuf and set its control state.
- */
 void sp_knot_update_ctrl(SPKnot *knot)
 {
     if (!knot->item) {
diff --git a/src/knot.h b/src/knot.h
index ad152b54c..73bb226c6 100644
--- a/src/knot.h
+++ b/src/knot.h
@@ -149,8 +149,14 @@ struct SPKnotClass {
     gdouble (* distance) (SPKnot *knot, Geom::Point const &pos, guint state);
 };
 
+/**
+ * Registers SPKnot class and returns its type number.
+ */
 GType sp_knot_get_type();
 
+/**
+ * Return new knot object.
+ */
 SPKnot *sp_knot_new(SPDesktop *desktop, gchar const *tip = NULL);
 
 #define SP_KNOT_IS_VISIBLE(k) ((k->flags & SP_KNOT_VISIBLE) != 0)
@@ -158,24 +164,56 @@ SPKnot *sp_knot_new(SPDesktop *desktop, gchar const *tip = NULL);
 #define SP_KNOT_IS_DRAGGING(k) ((k->flags & SP_KNOT_DRAGGING) != 0)
 #define SP_KNOT_IS_GRABBED(k) ((k->flags & SP_KNOT_GRABBED) != 0)
 
+/**
+ * Show knot on its canvas.
+ */
 void sp_knot_show(SPKnot *knot);
+
+/**
+ * Hide knot on its canvas.
+ */
 void sp_knot_hide(SPKnot *knot);
 
+/**
+ * Set flag in knot, with side effects.
+ */
 void sp_knot_set_flag(SPKnot *knot, guint flag, bool set);
+
+/**
+ * Update knot's pixbuf and set its control state.
+ */
 void sp_knot_update_ctrl(SPKnot *knot);
 
+/**
+ * Request or set new position for knot.
+ */
 void sp_knot_request_position(SPKnot *knot, Geom::Point const &pos, guint state);
+
+/**
+ * Return distance of point to knot's position; unused.
+ */
 gdouble sp_knot_distance(SPKnot *knot, Geom::Point const &p, guint state);
 
+/**
+ * Update knot for dragging and tell canvas an item was grabbed.
+ */
 void sp_knot_start_dragging(SPKnot *knot, Geom::Point const &p, gint x, gint y, guint32 etime);
 
-/** Moves knot and emits "moved" signal. */
+/**
+ * Move knot to new position and emits "moved" signal.
+ */
 void sp_knot_set_position(SPKnot *knot, Geom::Point const &p, guint state);
 
-/** Moves knot without any signal. */
+/**
+ * Move knot to new position, without emitting a MOVED signal.
+ */
 void sp_knot_moveto(SPKnot *knot, Geom::Point const &p);
 
 void sp_knot_handler_request_position(GdkEvent *event, SPKnot *knot);
+
+/**
+ * Returns position of knot.
+ */
 Geom::Point sp_knot_position(SPKnot const *knot);
 
 
diff --git a/src/libvpsc/block.cpp b/src/libvpsc/block.cpp
index 0bd662f28..8171780d4 100644
--- a/src/libvpsc/block.cpp
+++ b/src/libvpsc/block.cpp
@@ -1,8 +1,4 @@
-/**
- * \brief A block is a group of variables that must be moved together to improve
- * the goal function without violating already active constraints.
- * The variables in a block are spanned by a tree of active constraints.
- *
+/*
  * Authors:
  *   Tim Dwyer <tgdwyer@gmail.com>
  *
@@ -95,13 +91,7 @@ void Block::merge(Block* b, Constraint* c) {
 	f<<"  merged block="<<(b->deleted?*this:*b)<<endl;
 #endif
 }
-/**
- * Merges b into this block across c.  Can be either a
- * right merge or a left merge
- * @param b block to merge into this
- * @param c constraint being merged
- * @param distance separation required to satisfy c
- */
+
 void Block::merge(Block *b, Constraint *c, double dist) {
 #ifdef RECTANGLE_OVERLAP_LOGGING
 	ofstream f(LOGFILE,ios::app);
@@ -317,10 +307,7 @@ void Block::reset_active_lm(Variable* const v, Variable* const u) {
 		}
 	}
 }
-/**
- * finds the constraint with the minimum lagrange multiplier, that is, the constraint
- * that most wants to split
- */
+
 Constraint *Block::findMinLM() {
 	Constraint *min_lm=NULL;
 	reset_active_lm(vars->front(),NULL);
@@ -363,12 +350,7 @@ bool Block::isActiveDirectedPathBetween(Variable* u, Variable *v) {
 	}
 	return false;
 }
-/**
- * Block needs to be split because of a violated constraint between vl and vr.
- * We need to search the active constraint tree between l and r and find the constraint
- * with min lagrangrian multiplier and split at that point.
- * Returns the split constraint
- */
+
 Constraint* Block::splitBetween(Variable* const vl, Variable* const vr,
 	       	Block* &lb, Block* &rb) {
 #ifdef RECTANGLE_OVERLAP_LOGGING
@@ -383,11 +365,7 @@ Constraint* Block::splitBetween(Variable* const vl, Variable* const vr,
 	deleted = true;
 	return c;
 }
-/**
- * Creates two new blocks, l and r, and splits this block across constraint c,
- * placing the left subtree of constraints (and associated variables) into l
- * and the right into r.
- */
+
 void Block::split(Block* &l, Block* &r, Constraint* c) {
 	c->active=false;
 	l=new Block();
@@ -396,10 +374,6 @@ void Block::split(Block* &l, Block* &r, Constraint* c) {
 	populateSplitBlock(r,c->right,c->left);
 }
 
-/**
- * Computes the cost (squared euclidean distance from desired positions) of the
- * current positions for variables in this block
- */
 double Block::cost() {
 	double c = 0;
 	for (Vit v=vars->begin();v!=vars->end();++v) {
diff --git a/src/libvpsc/block.h b/src/libvpsc/block.h
index a4625b202..9c90fc87e 100644
--- a/src/libvpsc/block.h
+++ b/src/libvpsc/block.h
@@ -36,22 +36,57 @@ public:
 	double wposn;
 	Block(Variable* const v=NULL);
     virtual ~Block(void);
-	Constraint* findMinLM();
+
+    /**
+     * finds the constraint with the minimum lagrange multiplier, that is, the constraint
+     * that most wants to split
+     */
+    Constraint* findMinLM();
+
 	Constraint* findMinLMBetween(Variable* const lv, Variable* const rv);
 	Constraint* findMinInConstraint();
 	Constraint* findMinOutConstraint();
 	void deleteMinInConstraint();
 	void deleteMinOutConstraint();
 	double desiredWeightedPosition();
-	void merge(Block *b, Constraint *c, double dist);
+
+    /**
+     * Merges b into this block across c.  Can be either a
+     * right merge or a left merge
+     * @param b block to merge into this
+     * @param c constraint being merged
+     * @param distance separation required to satisfy c
+     */
+    void merge(Block *b, Constraint *c, double dist);
+
 	void merge(Block *b, Constraint *c);
 	void mergeIn(Block *b);
 	void mergeOut(Block *b);
-	void split(Block *&l, Block *&r, Constraint *c);
-	Constraint* splitBetween(Variable* vl, Variable* vr, Block* &lb, Block* &rb);
+
+    /**
+     * Creates two new blocks, l and r, and splits this block across constraint c,
+     * placing the left subtree of constraints (and associated variables) into l
+     * and the right into r.
+     */
+    void split(Block *&l, Block *&r, Constraint *c);
+
+    /**
+     * Block needs to be split because of a violated constraint between vl and vr.
+     * We need to search the active constraint tree between l and r and find the constraint
+     * with min lagrangrian multiplier and split at that point.
+     * Returns the split constraint
+     */
+    Constraint* splitBetween(Variable* vl, Variable* vr, Block* &lb, Block* &rb);
+
 	void setUpInConstraints();
 	void setUpOutConstraints();
-	double cost();
+
+    /**
+     * Computes the cost (squared euclidean distance from desired positions) of the
+     * current positions for variables in this block
+     */
+    double cost();
+
 	bool deleted;
 	long timeStamp;
 	PairingHeap<Constraint*> *in;
@@ -75,3 +110,13 @@ private:
 
 }
 #endif // SEEN_REMOVEOVERLAP_BLOCK_H
+/*
+  Local Variables:
+  mode:c++
+  c-file-style:"stroustrup"
+  c-file-offsets:((innamespace . 0)(inline-open . 0)(case-label . +))
+  indent-tabs-mode:nil
+  fill-column:99
+  End:
+*/
+// vim: filetype=cpp:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:fileencoding=utf-8:textwidth=99 :
diff --git a/src/libvpsc/blocks.cpp b/src/libvpsc/blocks.cpp
index fe0caacfc..7eff1e6c4 100644
--- a/src/libvpsc/blocks.cpp
+++ b/src/libvpsc/blocks.cpp
@@ -1,9 +1,5 @@
-/**
- * \brief A block structure defined over the variables
- *
- * A block structure defined over the variables such that each block contains
- * 1 or more variables, with the invariant that all constraints inside a block
- * are satisfied by keeping the variables fixed relative to one another
+/*
+ * A block structure defined over the variables.
  *
  * Authors:
  *   Tim Dwyer <tgdwyer@gmail.com>
@@ -47,10 +43,6 @@ Blocks::~Blocks(void)
 	clear();
 }
 
-/**
- * returns a list of variables with total ordering determined by the constraint 
- * DAG
- */
 list<Variable*> *Blocks::totalOrder() {
 	list<Variable*> *order = new list<Variable*>;
 	for(int i=0;i<nvs;i++) {
@@ -80,10 +72,7 @@ void Blocks::dfsVisit(Variable *v, list<Variable*> *order) {
 #endif
 	order->push_front(v);
 }
-/**
- * Processes incoming constraints, most violated to least, merging with the
- * neighbouring (left) block until no more violated constraints are found
- */
+
 void Blocks::mergeLeft(Block *r) {	
 #ifdef RECTANGLE_OVERLAP_LOGGING
 	ofstream f(LOGFILE,ios::app);
@@ -115,9 +104,7 @@ void Blocks::mergeLeft(Block *r) {
 	f<<"merged "<<*r<<endl;
 #endif
 }	
-/**
- * Symmetrical to mergeLeft
- */
+
 void Blocks::mergeRight(Block *l) {	
 #ifdef RECTANGLE_OVERLAP_LOGGING
 	ofstream f(LOGFILE,ios::app);
@@ -160,10 +147,7 @@ void Blocks::cleanup() {
 		}
 	}
 }
-/**
- * Splits block b across constraint c into two new blocks, l and r (c's left
- * and right sides respectively)
- */
+
 void Blocks::split(Block *b, Block *&l, Block *&r, Constraint *c) {
 	b->split(l,r,c);
 #ifdef RECTANGLE_OVERLAP_LOGGING
@@ -184,10 +168,7 @@ void Blocks::split(Block *b, Block *&l, Block *&r, Constraint *c) {
 	insert(l);
 	insert(r);
 }
-/**
- * returns the cost total squared distance of variables from their desired
- * positions
- */
+
 double Blocks::cost() {
 	double c = 0;
 	for(set<Block*>::iterator i=begin();i!=end();++i) {
diff --git a/src/libvpsc/blocks.h b/src/libvpsc/blocks.h
index e3223822e..b711a529f 100644
--- a/src/libvpsc/blocks.h
+++ b/src/libvpsc/blocks.h
@@ -33,21 +33,62 @@ class Constraint;
 class Blocks : public std::set<Block*>
 {
 public:
-	Blocks(const int n, Variable* const vs[]);
+    Blocks(const int n, Variable* const vs[]);
+
     virtual ~Blocks(void);
-	void mergeLeft(Block *r);
-	void mergeRight(Block *l);
-	void split(Block *b, Block *&l, Block *&r, Constraint *c);
-	std::list<Variable*> *totalOrder();
-	void cleanup();
-	double cost();
+
+    /**
+     * Processes incoming constraints, most violated to least, merging with the
+     * neighbouring (left) block until no more violated constraints are found.
+     */
+    void mergeLeft(Block *r);
+
+    /**
+     * Symmetrical to mergeLeft.
+     * @see mergeLeft
+     */
+    void mergeRight(Block *l);
+
+    /**
+     * Splits block b across constraint c into two new blocks, l and r (c's left
+     * and right sides respectively).
+     */
+    void split(Block *b, Block *&l, Block *&r, Constraint *c);
+
+    /**
+     * Returns a list of variables with total ordering determined by the constraint 
+     * DAG.
+     */
+    std::list<Variable*> *totalOrder();
+
+    void cleanup();
+
+    /**
+     * Returns the cost total squared distance of variables from their desired
+     * positions.
+     */
+    double cost();
+
 private:
-	void dfsVisit(Variable *v, std::list<Variable*> *order);
-	void removeBlock(Block *doomed);
-	Variable* const *vs;
-	int nvs;
+    void dfsVisit(Variable *v, std::list<Variable*> *order);
+
+    void removeBlock(Block *doomed);
+
+    Variable* const *vs;
+
+    int nvs;
 };
 
 extern long blockTimeCtr;
 }
 #endif // SEEN_REMOVEOVERLAP_BLOCKS_H
+/*
+  Local Variables:
+  mode:c++
+  c-file-style:"stroustrup"
+  c-file-offsets:((innamespace . 0)(inline-open . 0)(case-label . +))
+  indent-tabs-mode:nil
+  fill-column:99
+  End:
+*/
+// vim: filetype=cpp:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:fileencoding=utf-8:textwidth=99 :
diff --git a/src/libvpsc/csolve_VPSC.cpp b/src/libvpsc/csolve_VPSC.cpp
index 5176242d5..24459d09f 100644
--- a/src/libvpsc/csolve_VPSC.cpp
+++ b/src/libvpsc/csolve_VPSC.cpp
@@ -1,5 +1,5 @@
-/**
- * \brief Bridge for C programs to access solve_VPSC (which is in C++)
+/*
+ * Bridge for C programs to access solve_VPSC (which is in C++).
  *
  * Authors:
  *   Tim Dwyer <tgdwyer@gmail.com>
diff --git a/src/libvpsc/remove_rectangle_overlap.cpp b/src/libvpsc/remove_rectangle_overlap.cpp
index 4d2750b9e..381759f3c 100644
--- a/src/libvpsc/remove_rectangle_overlap.cpp
+++ b/src/libvpsc/remove_rectangle_overlap.cpp
@@ -1,5 +1,5 @@
-/** @file
- * @brief remove overlaps between a set of rectangles.
+/*
+ * remove overlaps between a set of rectangles.
  *
  * Authors:
  *   Tim Dwyer <tgdwyer@gmail.com>
@@ -28,18 +28,7 @@ using namespace vpsc;
 
 double Rectangle::xBorder=0;
 double Rectangle::yBorder=0;
-/**
- * Takes an array of n rectangles and moves them as little as possible
- * such that rectangles are separated by at least xBorder horizontally
- * and yBorder vertically
- *
- * Works in three passes: 
- * 1) removes some overlap horizontally
- * 2) removes remaining overlap vertically
- * 3) a last horizontal pass removes all overlap starting from original
- *    x-positions - this corrects the case where rectangles were moved 
- *    too much in the first pass.
- */
+
 void removeRectangleOverlap(unsigned n, Rectangle *rs[], double xBorder, double yBorder) {
 	try {
 	// The extra gap avoids numerical imprecision problems
diff --git a/src/libvpsc/remove_rectangle_overlap.h b/src/libvpsc/remove_rectangle_overlap.h
index 1af90a754..3e2f4cc8f 100644
--- a/src/libvpsc/remove_rectangle_overlap.h
+++ b/src/libvpsc/remove_rectangle_overlap.h
@@ -1,5 +1,5 @@
-/** @file
- * @brief Declaration of main internal remove-overlaps function.
+/*
+ * Declaration of main internal remove-overlaps function.
  */
 /* Authors:
  *   Tim Dwyer <tgdwyer@gmail.com>
@@ -16,6 +16,18 @@ namespace vpsc {
 	class Rectangle;
 }
 
+/**
+ * Takes an array of n rectangles and moves them as little as possible
+ * such that rectangles are separated by at least xBorder horizontally
+ * and yBorder vertically
+ *
+ * Works in three passes: 
+ * 1) removes some overlap horizontally
+ * 2) removes remaining overlap vertically
+ * 3) a last horizontal pass removes all overlap starting from original
+ *    x-positions - this corrects the case where rectangles were moved 
+ *    too much in the first pass.
+ */
 void removeRectangleOverlap(unsigned n, vpsc::Rectangle *rs[], double xBorder, double yBorder);
 
 
diff --git a/src/libvpsc/solve_VPSC.cpp b/src/libvpsc/solve_VPSC.cpp
index ec2c48d46..f9bed649c 100644
--- a/src/libvpsc/solve_VPSC.cpp
+++ b/src/libvpsc/solve_VPSC.cpp
@@ -1,5 +1,5 @@
-/**
- * \brief Solve an instance of the "Variable Placement with Separation
+/*
+ * Solve an instance of the "Variable Placement with Separation
  * Constraints" problem.
  *
  * Authors:
@@ -59,16 +59,7 @@ void Solver::printBlocks() {
 	}
 #endif
 }
-/**
-* Produces a feasible - though not necessarily optimal - solution by
-* examining blocks in the partial order defined by the directed acyclic
-* graph of constraints. For each block (when processing left to right) we
-* maintain the invariant that all constraints to the left of the block
-* (incoming constraints) are satisfied. This is done by repeatedly merging
-* blocks into bigger blocks across violated constraints (most violated
-* first) fixing the position of variables inside blocks relative to one
-* another so that constraints internal to the block are satisfied.
-*/
+
 void Solver::satisfy() {
 	list<Variable*> *vs=bs->totalOrder();
 	for(list<Variable*>::iterator i=vs->begin();i!=vs->end();++i) {
@@ -129,12 +120,7 @@ void Solver::refine() {
 		}
 	}
 }
-/**
- * Calculate the optimal solution. After using satisfy() to produce a
- * feasible solution, refine() examines each block to see if further
- * refinement is possible by splitting the block. This is done repeatedly
- * until no further improvement is possible.
- */
+
 void Solver::solve() {
 	satisfy();
 	refine();
@@ -156,19 +142,7 @@ void IncSolver::solve() {
 #endif
 	} while(fabs(lastcost-cost)>0.0001);
 }
-/**
- * incremental version of satisfy that allows refinement after blocks are
- * moved.
- *
- *  - move blocks to new positions
- *  - repeatedly merge across most violated constraint until no more
- *    violated constraints exist
- *
- * Note: there is a special case to handle when the most violated constraint
- * is between two variables in the same block.  Then, we must split the block
- * over an active constraint between the two variables.  We choose the 
- * constraint with the most negative lagrangian multiplier. 
- */
+
 void IncSolver::satisfy() {
 #ifdef RECTANGLE_OVERLAP_LOGGING
 	ofstream f(LOGFILE,ios::app);
@@ -270,10 +244,6 @@ void IncSolver::splitBlocks() {
 	bs->cleanup();
 }
 
-/**
- * Scan constraint list for the most violated constraint, or the first equality
- * constraint
- */
 Constraint* IncSolver::mostViolated(ConstraintList &l) {
 	double minSlack = DBL_MAX;
 	Constraint* v=NULL;
diff --git a/src/libvpsc/solve_VPSC.h b/src/libvpsc/solve_VPSC.h
index 84f646226..e416ef9c6 100644
--- a/src/libvpsc/solve_VPSC.h
+++ b/src/libvpsc/solve_VPSC.h
@@ -34,8 +34,26 @@ class Blocks;
  */
 class Solver {
 public:
-	virtual void satisfy();
-	virtual void solve();
+
+    /**
+     * Produces a feasible - though not necessarily optimal - solution by
+     * examining blocks in the partial order defined by the directed acyclic
+     * graph of constraints. For each block (when processing left to right) we
+     * maintain the invariant that all constraints to the left of the block
+     * (incoming constraints) are satisfied. This is done by repeatedly merging
+     * blocks into bigger blocks across violated constraints (most violated
+     * first) fixing the position of variables inside blocks relative to one
+     * another so that constraints internal to the block are satisfied.
+     */
+    virtual void satisfy();
+
+    /**
+     * Calculate the optimal solution. After using satisfy() to produce a
+     * feasible solution, refine() examines each block to see if further
+     * refinement is possible by splitting the block. This is done repeatedly
+     * until no further improvement is possible.
+     */
+    virtual void solve();
 
 	Solver(const unsigned n, Variable* const vs[], const unsigned m, Constraint *cs[]);
 	virtual ~Solver();
@@ -56,16 +74,51 @@ private:
 
 class IncSolver : public Solver {
 public:
-	unsigned splitCnt;
-	void satisfy();
-	void solve();
-	void moveBlocks();
-	void splitBlocks();
-	IncSolver(const unsigned n, Variable* const vs[], const unsigned m, Constraint *cs[]);
+    unsigned splitCnt;
+
+    /**
+     * incremental version of satisfy that allows refinement after blocks are
+     * moved.
+     *
+     *  - move blocks to new positions
+     *  - repeatedly merge across most violated constraint until no more
+     *    violated constraints exist
+     *
+     * Note: there is a special case to handle when the most violated constraint
+     * is between two variables in the same block.  Then, we must split the block
+     * over an active constraint between the two variables.  We choose the 
+     * constraint with the most negative lagrangian multiplier. 
+     */
+    void satisfy();
+
+    void solve();
+
+    void moveBlocks();
+
+    void splitBlocks();
+
+    IncSolver(const unsigned n, Variable* const vs[], const unsigned m, Constraint *cs[]);
 private:
-	typedef std::vector<Constraint*> ConstraintList;
-	ConstraintList inactive;
-	Constraint* mostViolated(ConstraintList &l);
+
+    typedef std::vector<Constraint*> ConstraintList;
+
+    ConstraintList inactive;
+
+    /**
+     * Scan constraint list for the most violated constraint, or the first equality
+     * constraint.
+     */
+    Constraint* mostViolated(ConstraintList &l);
 };
 }
 #endif // SEEN_REMOVEOVERLAP_SOLVE_VPSC_H
+/*
+  Local Variables:
+  mode:c++
+  c-file-style:"stroustrup"
+  c-file-offsets:((innamespace . 0)(inline-open . 0)(case-label . +))
+  indent-tabs-mode:nil
+  fill-column:99
+  End:
+*/
+// vim: filetype=cpp:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:fileencoding=utf-8:textwidth=99 :
diff --git a/src/libvpsc/variable.cpp b/src/libvpsc/variable.cpp
index 19dc0746a..29bf8dc5c 100644
--- a/src/libvpsc/variable.cpp
+++ b/src/libvpsc/variable.cpp
@@ -1,5 +1,4 @@
-/**
- *
+/*
  * Authors:
  *   Tim Dwyer <tgdwyer@gmail.com>
  *
@@ -8,6 +7,7 @@
  * Released under GNU LGPL.  Read the file 'COPYING' for more information.
  */
 #include "variable.h"
+
 namespace vpsc {
 std::ostream& operator <<(std::ostream &os, const Variable &v) {
 	os << "(" << v.id << "=" << v.position() << ")";
diff --git a/src/line-snapper.cpp b/src/line-snapper.cpp
index 45b03c38b..6a50e8485 100644
--- a/src/line-snapper.cpp
+++ b/src/line-snapper.cpp
@@ -1,5 +1,4 @@
-/**
- * \file line-snapper.cpp
+/*
  * LineSnapper class.
  *
  * Authors:
diff --git a/src/main.cpp b/src/main.cpp
index 501a3e5d2..63fd4a454 100644
--- a/src/main.cpp
+++ b/src/main.cpp
@@ -1,4 +1,4 @@
-/** \file
+/*
  * Inkscape - an ambitious vector drawing program
  *
  * Authors:
diff --git a/src/object-hierarchy.cpp b/src/object-hierarchy.cpp
index e6a1618a7..f2bf177dc 100644
--- a/src/object-hierarchy.cpp
+++ b/src/object-hierarchy.cpp
@@ -1,4 +1,4 @@
-/** \file
+/*
  * Object hierarchy implementation.
  *
  * Authors:
@@ -16,10 +16,6 @@
 
 namespace Inkscape {
 
-/**
- * Create new object hierarchy.
- * \param top The first entry if non-NULL.
- */
 ObjectHierarchy::ObjectHierarchy(SPObject *top) {
     if (top) {
         _addBottom(top);
@@ -30,17 +26,11 @@ ObjectHierarchy::~ObjectHierarchy() {
     _clear();
 }
 
-/**
- * Remove all entries.
- */
 void ObjectHierarchy::clear() {
     _clear();
     _changed_signal.emit(NULL, NULL);
 }
 
-/**
- * Trim or expand hierarchy on top such that object becomes top entry.
- */
 void ObjectHierarchy::setTop(SPObject *object) {
     g_return_if_fail(object != NULL);
 
@@ -62,10 +52,6 @@ void ObjectHierarchy::setTop(SPObject *object) {
     _changed_signal.emit(top(), bottom());
 }
 
-/**
- * Add hierarchy from junior's parent to senior to this
- * hierarchy's top.
- */
 void ObjectHierarchy::_addTop(SPObject *senior, SPObject *junior) {
     g_assert(junior != NULL);
     g_assert(senior != NULL);
@@ -77,19 +63,12 @@ void ObjectHierarchy::_addTop(SPObject *senior, SPObject *junior) {
     } while ( object != senior );
 }
 
-/**
- * Add object to top of hierarchy.
- * \pre object!=NULL
- */
 void ObjectHierarchy::_addTop(SPObject *object) {
     g_assert(object != NULL);
     _hierarchy.push_back(_attach(object));
     _added_signal.emit(object);
 }
 
-/**
- * Remove all objects above limit from hierarchy.
- */
 void ObjectHierarchy::_trimAbove(SPObject *limit) {
     while ( !_hierarchy.empty() && _hierarchy.back().object != limit ) {
         SPObject *object=_hierarchy.back().object;
@@ -102,9 +81,6 @@ void ObjectHierarchy::_trimAbove(SPObject *limit) {
     }
 }
 
-/**
- * Trim or expand hierarchy at bottom such that object becomes bottom entry.
- */
 void ObjectHierarchy::setBottom(SPObject *object) {
     g_return_if_fail(object != NULL);
 
@@ -137,10 +113,6 @@ void ObjectHierarchy::setBottom(SPObject *object) {
     _changed_signal.emit(top(), bottom());
 }
 
-/**
- * Remove all objects under given object.
- * \param limit If NULL, remove all.
- */
 void ObjectHierarchy::_trimBelow(SPObject *limit) {
     while ( !_hierarchy.empty() && _hierarchy.front().object != limit ) {
         SPObject *object=_hierarchy.front().object;
@@ -152,9 +124,6 @@ void ObjectHierarchy::_trimBelow(SPObject *limit) {
     }
 }
 
-/**
- * Add hierarchy from senior to junior to this hierarchy's bottom.
- */
 void ObjectHierarchy::_addBottom(SPObject *senior, SPObject *junior) {
     g_assert(junior != NULL);
     g_assert(senior != NULL);
@@ -165,10 +134,6 @@ void ObjectHierarchy::_addBottom(SPObject *senior, SPObject *junior) {
     }
 }
 
-/**
- * Add object at bottom of hierarchy.
- * \pre object!=NULL
- */
 void ObjectHierarchy::_addBottom(SPObject *object) {
     g_assert(object != NULL);
     _hierarchy.push_front(_attach(object));
diff --git a/src/object-hierarchy.h b/src/object-hierarchy.h
index d510e7e69..34a81cf9f 100644
--- a/src/object-hierarchy.h
+++ b/src/object-hierarchy.h
@@ -36,7 +36,13 @@ namespace Inkscape {
  */
 class ObjectHierarchy {
 public:
+
+    /**
+     * Create new object hierarchy.
+     * @param top The first entry if non-NULL.
+     */
     ObjectHierarchy(SPObject *top=NULL);
+
     ~ObjectHierarchy();
 
     bool contains(SPObject *object);
@@ -52,16 +58,27 @@ public:
         return _changed_signal.connect(slot);
     }
 
+    /**
+     * Remove all entries.
+     */
     void clear();
 
     SPObject *top() {
         return !_hierarchy.empty() ? _hierarchy.back().object : NULL;
     }
+
+    /**
+     * Trim or expand hierarchy on top such that object becomes top entry.
+     */
     void setTop(SPObject *object);
 
     SPObject *bottom() {
         return !_hierarchy.empty() ? _hierarchy.front().object : NULL;
     }
+
+    /**
+     * Trim or expand hierarchy at bottom such that object becomes bottom entry.
+     */
     void setBottom(SPObject *object);
 
 private:
@@ -74,23 +91,45 @@ private:
     };
 
     ObjectHierarchy(ObjectHierarchy const &); // no copy
+
     void operator=(ObjectHierarchy const &); // no assign
 
-    /// @brief adds objects in range [senior, junior) to the top
+    /**
+     * Add hierarchy from junior's parent to senior to this
+     * hierarchy's top.
+     */
     void _addTop(SPObject *senior, SPObject *junior);
-    /// @brief adds one object to the top
+
+    /**
+     * Add object to top of hierarchy.
+     * \pre object!=NULL.
+     */
     void _addTop(SPObject *object);
-    /// @brief removes all objects above the limit object
+
+    /**
+     * Remove all objects above limit from hierarchy.
+     */
     void _trimAbove(SPObject *limit);
 
-    /// @brief adds objects in range (senior, junior] to the bottom
+    /**
+     * Add hierarchy from senior to junior, in range (senior, junior], to this hierarchy's bottom.
+     */
     void _addBottom(SPObject *senior, SPObject *junior);
-    /// @brief adds one object to the bottom
+
+    /**
+     * Add object at bottom of hierarchy.
+     * \pre object!=NULL
+     */
     void _addBottom(SPObject *object);
-    /// @brief removes all objects below the limit object
+
+    /**
+     * Remove all objects under given object.
+     * @param limit If NULL, remove all.
+     */
     void _trimBelow(SPObject *limit);
 
     Record _attach(SPObject *object);
+
     void _detach(Record &record);
 
     void _clear() { _trimBelow(NULL); }
diff --git a/src/object-snapper.cpp b/src/object-snapper.cpp
index bf8cf166a..e7d9b774d 100644
--- a/src/object-snapper.cpp
+++ b/src/object-snapper.cpp
@@ -1,5 +1,4 @@
-/**
- *  \file object-snapper.cpp
+/*
  *  Snapping things to objects.
  *
  * Authors:
@@ -58,9 +57,6 @@ Inkscape::ObjectSnapper::~ObjectSnapper()
     delete _paths_to_snap_to;
 }
 
-/**
- *  \return Snap tolerance (desktop coordinates); depends on current zoom so that it's always the same in screen pixels
- */
 Geom::Coord Inkscape::ObjectSnapper::getSnapperTolerance() const
 {
     SPDesktop const *dt = _snapmanager->getDesktop();
@@ -73,14 +69,6 @@ bool Inkscape::ObjectSnapper::getSnapperAlwaysSnap() const
     return _snapmanager->snapprefs.getObjectTolerance() == 10000; //TODO: Replace this threshold of 10000 by a constant; see also tolerance-slider.cpp
 }
 
-/**
- *  Find all items within snapping range.
- *  \param parent Pointer to the document's root, or to a clipped path or mask object
- *  \param it List of items to ignore
- *  \param bbox_to_snap Bounding box hulling the whole bunch of points, all from the same selection and having the same transformation
- *  \param clip_or_mask The parent object being passed is either a clip or mask
- */
-
 void Inkscape::ObjectSnapper::_findCandidates(SPObject* parent,
                                               std::vector<SPItem const *> const *it,
                                               bool const &first_point,
@@ -354,10 +342,7 @@ void Inkscape::ObjectSnapper::_snapTranslatingGuide(IntermSnapResults &isr,
 }
 
 
-/**
- * Returns index of first NR_END bpath in array.
- */
-
+/// @todo investigate why Geom::Point p is passed in but ignored.
 void Inkscape::ObjectSnapper::_collectPaths(Geom::Point /*p*/,
                                          SnapSourceType const source_type,
                                          bool const &first_point) const
@@ -767,9 +752,6 @@ void Inkscape::ObjectSnapper::constrainedSnap( IntermSnapResults &isr,
     }
 }
 
-/**
- *  \return true if this Snapper will snap at least one kind of point.
- */
 bool Inkscape::ObjectSnapper::ThisSnapperMightSnap() const
 {
     return true;
diff --git a/src/object-snapper.h b/src/object-snapper.h
index 5526040f3..d51cade93 100644
--- a/src/object-snapper.h
+++ b/src/object-snapper.h
@@ -32,9 +32,16 @@ public:
     ObjectSnapper(SnapManager *sm, Geom::Coord const d);
     ~ObjectSnapper();
 
+    /**
+     * @return true if this Snapper will snap at least one kind of point.
+     */
     bool ThisSnapperMightSnap() const;
 
+    /**
+     * @return Snap tolerance (desktop coordinates); depends on current zoom so that it's always the same in screen pixels.
+     */
     Geom::Coord getSnapperTolerance() const; //returns the tolerance of the snapper in screen pixels (i.e. independent of zoom)
+
     bool getSnapperAlwaysSnap() const; //if true, then the snapper will always snap, regardless of its tolerance
 
     void freeSnap(IntermSnapResults &isr,
@@ -56,6 +63,13 @@ private:
     std::vector<SnapCandidatePoint> *_points_to_snap_to;
     std::vector<SnapCandidatePath > *_paths_to_snap_to;
 
+    /**
+     * Find all items within snapping range.
+     * @param parent Pointer to the document's root, or to a clipped path or mask object.
+     * @param it List of items to ignore.
+     * @param bbox_to_snap Bounding box hulling the whole bunch of points, all from the same selection and having the same transformation.
+     * @param clip_or_mask The parent object being passed is either a clip or mask.
+     */
     void _findCandidates(SPObject* parent,
                        std::vector<SPItem const *> const *it,
                        bool const &first_point,
@@ -88,6 +102,9 @@ private:
 
     bool isUnselectedNode(Geom::Point const &point, std::vector<Inkscape::SnapCandidatePoint> const *unselected_nodes) const;
 
+    /**
+     * Returns index of first NR_END bpath in array.
+     */
     void _collectPaths(Geom::Point p,
                       Inkscape::SnapSourceType const source_type,
                       bool const &first_point) const;
diff --git a/src/registrytool.cpp b/src/registrytool.cpp
index af41c3eaf..d2cec0080 100644
--- a/src/registrytool.cpp
+++ b/src/registrytool.cpp
@@ -1,10 +1,6 @@
-/**
+/*
  * Inkscape Registry Tool
  *
- * This simple tool is intended for allowing Inkscape to append subdirectories
- * to its path.  This will allow extensions and other files to be accesses
- * without explicit user intervention.
- *
  * Authors:
  *   Bob Jamison
  *
@@ -52,9 +48,6 @@ KeyTableEntry keyTable[] =
 };
 
 
-/**
- * Set the string value of a key/name registry entry
- */ 
 bool RegistryTool::setStringValue(const Glib::ustring &keyNameArg,
                                   const Glib::ustring &valueName,
                                   const Glib::ustring &value)
@@ -108,9 +101,6 @@ bool RegistryTool::setStringValue(const Glib::ustring &keyNameArg,
 
 
 
-/**
- * Get the full path, directory, and base file name of this running executable
- */ 
 bool RegistryTool::getExeInfo(Glib::ustring &fullPath,
                               Glib::ustring &path,
                               Glib::ustring &exeName)
@@ -137,10 +127,6 @@ bool RegistryTool::getExeInfo(Glib::ustring &fullPath,
 
 
 
-/**
- * Append our subdirectories to the Application Path for this
- * application
- */  
 bool RegistryTool::setPathInfo()
 {
     Glib::ustring fullPath;
@@ -181,7 +167,7 @@ bool RegistryTool::setPathInfo()
 #ifdef TESTREG
 
 
-/**
+/*
  * Compile this file with
  *      g++ -DTESTREG registrytool.cpp -o registrytool
  *  to run these tests.
diff --git a/src/registrytool.h b/src/registrytool.h
index 7bb00b8f5..0a8139184 100644
--- a/src/registrytool.h
+++ b/src/registrytool.h
@@ -41,14 +41,24 @@ public:
     virtual ~RegistryTool()
         {}
 
+    /**
+     * Set the string value of a key/name registry entry.
+     */ 
     bool setStringValue(const Glib::ustring &key,
                         const Glib::ustring &valueName,
                         const Glib::ustring &value);
 
+    /**
+     * Get the full path, directory, and base file name of this running executable.
+     */ 
     bool getExeInfo(Glib::ustring &fullPath,
                     Glib::ustring &path,
                     Glib::ustring &exeName);
 
+    /**
+     * Append our subdirectories to the Application Path for this
+     * application.
+     */  
     bool setPathInfo();
 
 
diff --git a/src/rubberband.cpp b/src/rubberband.cpp
index 00f87cf8e..cdf41d400 100644
--- a/src/rubberband.cpp
+++ b/src/rubberband.cpp
@@ -1,5 +1,4 @@
-/**
- * \file src/rubberband.cpp
+/*
  * Rubberbanding selector.
  *
  * Author:
diff --git a/src/selection.cpp b/src/selection.cpp
index 5376311b1..ff444fa98 100644
--- a/src/selection.cpp
+++ b/src/selection.cpp
@@ -1,4 +1,4 @@
-/** \file
+/*
  * Per-desktop selection container
  *
  * Authors:
@@ -414,7 +414,6 @@ Geom::OptRect Selection::documentBounds(SPItem::BBoxType type) const
     return bbox;
 }
 
-/** Extract the position of the center from the first selected object */
 // If we have a selection of multiple items, then the center of the first item
 // will be returned; this is also the case in SelTrans::centerRequest()
 boost::optional<Geom::Point> Selection::center() const {
@@ -434,9 +433,6 @@ boost::optional<Geom::Point> Selection::center() const {
     }
 }
 
-/**
- * Compute the list of points in the selection that are to be considered for snapping from.
- */
 std::vector<Inkscape::SnapCandidatePoint> Selection::getSnapPoints(SnapPreferences const *snapprefs) const {
     GSList const *items = const_cast<Selection *>(this)->itemList();
 
@@ -458,6 +454,7 @@ std::vector<Inkscape::SnapCandidatePoint> Selection::getSnapPoints(SnapPreferenc
 
     return p;
 }
+
 // TODO: both getSnapPoints and getSnapPointsConvexHull are called, subsequently. Can we do this more efficient?
 // Why do we need to include the transformation center in one case and not the other?
 std::vector<Inkscape::SnapCandidatePoint> Selection::getSnapPointsConvexHull(SnapPreferences const *snapprefs) const {
diff --git a/src/selection.h b/src/selection.h
index a151be500..168c70dd4 100644
--- a/src/selection.h
+++ b/src/selection.h
@@ -260,7 +260,8 @@ public:
     boost::optional<Geom::Point> center() const;
 
     /**
-     * Gets the selection's snap points.
+     * Compute the list of points in the selection that are to be considered for snapping from.
+     *
      * @return Selection's snap points
      */
     std::vector<Inkscape::SnapCandidatePoint> getSnapPoints(SnapPreferences const *snapprefs) const;
diff --git a/src/snap-preferences.cpp b/src/snap-preferences.cpp
index b3a95877f..50bb8ef2c 100644
--- a/src/snap-preferences.cpp
+++ b/src/snap-preferences.cpp
@@ -1,6 +1,5 @@
-/**
- *  \file snap-preferences.cpp
- *  Storing of snapping preferences.
+/*
+ * Storing of snapping preferences.
  *
  * Authors:
  *   Diederik van Lierop <mail@diedenrezi.nl>
@@ -97,11 +96,6 @@ bool Inkscape::SnapPreferences::getSnapModeAny() const
     return (_snap_from != 0);
 }
 
-/**
- *  Turn on/off snapping of specific point types.
- *  \param t Point type.
- *  \param s true to snap to this point type, otherwise false;
- */
 void Inkscape::SnapPreferences::setSnapFrom(Inkscape::SnapSourceType t, bool s)
 {
     if (s) {
@@ -111,30 +105,11 @@ void Inkscape::SnapPreferences::setSnapFrom(Inkscape::SnapSourceType t, bool s)
     }
 }
 
-/**
- *  \param t Point type.
- *  \return true if snapper will snap this type of point, otherwise false.
- */
 bool Inkscape::SnapPreferences::getSnapFrom(Inkscape::SnapSourceType t) const
 {
     return (_snap_from & t);
 }
-/**
- *  Map snap target to array index.
- *
- *  The status of each snap toggle (in the snap toolbar) is stored as a boolean value in an array. This method returns the position
- *  of relevant boolean in that array, for any given type of snap target. For most snap targets, the enumerated value of that targets
- *  matches the position in the array (primary snap targets). This however does not hold for snap targets which don't have their own
- *  toggle button (secondary snap targets).
- *
- *  PS:
- *  - For snap sources, just pass the corresponding snap target instead (each snap source should have a twin snap target, but not vice versa)
- *  - All parameters are passed by reference, and will be overwritten
- *
- *  @param target Stores the enumerated snap target,  which can be modified to correspond to the array index of this snap target
- *  @param always_on If true, then this snap target is always active and cannot be toggled
- *  @param group_on If true, then this snap target is in a snap group that has been enabled (e.g. bbox group, nodes/paths group, or "others" group
- */
+
 void Inkscape::SnapPreferences::_mapTargetToArrayIndex(Inkscape::SnapTargetType &target, bool &always_on, bool &group_on) const
 {
     if (target & SNAPTARGET_BBOX_CATEGORY) {
diff --git a/src/snap-preferences.h b/src/snap-preferences.h
index 8044d0aa7..0db135f5d 100644
--- a/src/snap-preferences.h
+++ b/src/snap-preferences.h
@@ -46,7 +46,17 @@ public:
     void setSnapPostponedGlobally(bool postponed) {_snap_postponed_globally = postponed;}
     bool getSnapPostponedGlobally() const {return _snap_postponed_globally;}
 
+    /**
+     * Turn on/off snapping of specific point types.
+     * @param t Point type.
+     * @param s true to snap to this point type, otherwise false.
+     */
     void setSnapFrom(Inkscape::SnapSourceType t, bool s);
+
+    /**
+     * @param t Point type.
+     * @return true if snapper will snap this type of point, otherwise false.
+     */
     bool getSnapFrom(Inkscape::SnapSourceType t) const;
 
     bool getStrictSnapping() const {return _strict_snapping;}
@@ -60,7 +70,25 @@ public:
     void setObjectTolerance(gdouble val) {_object_tolerance = val;}
 
 private:
+
+    /**
+     * Map snap target to array index.
+     *
+     * The status of each snap toggle (in the snap toolbar) is stored as a boolean value in an array. This method returns the position
+     * of relevant boolean in that array, for any given type of snap target. For most snap targets, the enumerated value of that targets
+     * matches the position in the array (primary snap targets). This however does not hold for snap targets which don't have their own
+     * toggle button (secondary snap targets).
+     *
+     * PS:
+     * - For snap sources, just pass the corresponding snap target instead (each snap source should have a twin snap target, but not vice versa)
+     * - All parameters are passed by reference, and will be overwritten
+     *
+     * @param target Stores the enumerated snap target,  which can be modified to correspond to the array index of this snap target.
+     * @param always_on If true, then this snap target is always active and cannot be toggled.
+     * @param group_on If true, then this snap target is in a snap group that has been enabled (e.g. bbox group, nodes/paths group, or "others" group.
+     */
     void _mapTargetToArrayIndex(Inkscape::SnapTargetType &target, bool &always_on, bool &group_on) const;
+
     int _active_snap_targets[Inkscape::SNAPTARGET_MAX_ENUM_VALUE];
 
     bool _snap_enabled_globally; // Toggles ALL snapping
diff --git a/src/snap.cpp b/src/snap.cpp
index 56b48d507..5f4872bba 100644
--- a/src/snap.cpp
+++ b/src/snap.cpp
@@ -1,5 +1,4 @@
-/**
- * \file snap.cpp
+/*
  * SnapManager class.
  *
  * Authors:
@@ -37,12 +36,6 @@
 #include "util/mathfns.h"
 using std::vector;
 
-/**
- *  Construct a SnapManager for a SPNamedView.
- *
- *  \param v `Owning' SPNamedView.
- */
-
 SnapManager::SnapManager(SPNamedView const *v) :
     guide(this, 0),
     object(this, 0),
@@ -55,18 +48,6 @@ SnapManager::SnapManager(SPNamedView const *v) :
 {
 }
 
-/**
- *  Return a list of snappers.
- *
- *  Inkscape snaps to objects, grids, and guides. For each of these snap targets a
- *  separate class is used, which has been derived from the base Snapper class. The
- *  getSnappers() method returns a list of pointers to instances of this class. This
- *  list contains exactly one instance of the guide snapper and of the object snapper
- *  class, but any number of grid snappers (because each grid has its own snapper
- *  instance)
- *
- *  @return List of snappers that we use.
- */
 SnapManager::SnapperList SnapManager::getSnappers() const
 {
     SnapManager::SnapperList s;
@@ -79,16 +60,6 @@ SnapManager::SnapperList SnapManager::getSnappers() const
     return s;
 }
 
-/**
- *  Return a list of gridsnappers.
- *
- *  Each grid has its own instance of the snapper class. This way snapping can
- *  be enabled per grid individually. A list will be returned containing the
- *  pointers to these instances, but only for grids that are being displayed
- *  and for which snapping is enabled.
- *
- *  @return List of gridsnappers that we use.
- */
 SnapManager::SnapperList SnapManager::getGridSnappers() const
 {
     SnapperList s;
@@ -103,17 +74,6 @@ SnapManager::SnapperList SnapManager::getGridSnappers() const
     return s;
 }
 
-/**
- * Return true if any snapping might occur, whether its to grids, guides or objects.
- *
- * Each snapper instance handles its own snapping target, e.g. grids, guides or
- * objects. This method iterates through all these snapper instances and returns
- * true if any of the snappers might possible snap, considering only the relevant
- * snapping preferences.
- *
- * @return true if one of the snappers will try to snap to something.
- */
-
 bool SnapManager::someSnapperMightSnap() const
 {
     if ( !snapprefs.getSnapEnabledGlobally() || snapprefs.getSnapPostponedGlobally() ) {
@@ -129,10 +89,6 @@ bool SnapManager::someSnapperMightSnap() const
     return (i != s.end());
 }
 
-/**
- * \return true if one of the grids might be snapped to.
- */
-
 bool SnapManager::gridSnapperMightSnap() const
 {
     if ( !snapprefs.getSnapEnabledGlobally() || snapprefs.getSnapPostponedGlobally() ) {
@@ -148,30 +104,6 @@ bool SnapManager::gridSnapperMightSnap() const
     return (i != s.end());
 }
 
-/**
- *  Try to snap a point to grids, guides or objects.
- *
- *  Try to snap a point to grids, guides or objects, in two degrees-of-freedom,
- *  i.e. snap in any direction on the two dimensional canvas to the nearest
- *  snap target. freeSnapReturnByRef() is equal in snapping behavior to
- *  freeSnap(), but the former returns the snapped point trough the referenced
- *  parameter p. This parameter p initially contains the position of the snap
- *  source and will we overwritten by the target position if snapping has occurred.
- *  This makes snapping transparent to the calling code. If this is not desired
- *  because either the calling code must know whether snapping has occurred, or
- *  because the original position should not be touched, then freeSnap() should be
- *  called instead.
- *
- *  PS:
- *  1) SnapManager::setup() must have been called before calling this method,
- *  but only once for a set of points
- *  2) Only to be used when a single source point is to be snapped; it assumes
- *  that source_num = 0, which is inefficient when snapping sets our source points
- *
- *  @param p Current position of the snap source; will be overwritten by the position of the snap target if snapping has occurred
- *  @param source_type Detailed description of the source type, will be used by the snap indicator
- *  @param bbox_to_snap Bounding box hulling the set of points, all from the same selection and having the same transformation
- */
 void SnapManager::freeSnapReturnByRef(Geom::Point &p,
                                       Inkscape::SnapSourceType const source_type,
                                       Geom::OptRect const &bbox_to_snap) const
@@ -188,21 +120,6 @@ void SnapManager::freeSnapReturnByRef(Geom::Point &p,
     s.getPointIfSnapped(p);
 }
 
-/**
- *  Try to snap a point to grids, guides or objects.
- *
- *  Try to snap a point to grids, guides or objects, in two degrees-of-freedom,
- *  i.e. snap in any direction on the two dimensional canvas to the nearest
- *  snap target. freeSnap() is equal in snapping behavior to
- *  freeSnapReturnByRef(). Please read the comments of the latter for more details
- *
- *  PS: SnapManager::setup() must have been called before calling this method,
- *  but only once for a set of points
- *
- *  @param p Source point to be snapped
- *  @param bbox_to_snap Bounding box hulling the set of points, all from the same selection and having the same transformation
- *  @return An instance of the SnappedPoint class, which holds data on the snap source, snap target, and various metrics
- */
 Inkscape::SnappedPoint SnapManager::freeSnap(Inkscape::SnapCandidatePoint const &p,
                                              Geom::OptRect const &bbox_to_snap) const
 {
@@ -237,24 +154,6 @@ void SnapManager::preSnap(Inkscape::SnapCandidatePoint const &p)
     }
 }
 
-/**
- * Snap to the closest multiple of a grid pitch.
- *
- * When pasting, we would like to snap to the grid. Problem is that we don't know which
- * nodes were aligned to the grid at the time of copying, so we don't know which nodes
- * to snap. If we'd snap an unaligned node to the grid, previously aligned nodes would
- * become unaligned. That's undesirable. Instead we will make sure that the offset
- * between the source and its pasted copy is a multiple of the grid pitch. If the source
- * was aligned, then the copy will therefore also be aligned.
- *
- * PS: Whether we really find a multiple also depends on the snapping range! Most users
- * will have "always snap" enabled though, in which case a multiple will always be found.
- * PS2: When multiple grids are present then the result will become ambiguous. There is no
- * way to control to which grid this method will snap.
- *
- * @param t Vector that represents the offset of the pasted copy with respect to the original
- * @return Offset vector after snapping to the closest multiple of a grid pitch
- */
 Geom::Point SnapManager::multipleOfGridPitch(Geom::Point const &t, Geom::Point const &origin)
 {
     if (!snapprefs.getSnapEnabledGlobally() || snapprefs.getSnapPostponedGlobally())
@@ -310,35 +209,6 @@ Geom::Point SnapManager::multipleOfGridPitch(Geom::Point const &t, Geom::Point c
     return t;
 }
 
-/**
- *  Try to snap a point along a constraint line to grids, guides or objects.
- *
- *  Try to snap a point to grids, guides or objects, in only one degree-of-freedom,
- *  i.e. snap in a specific direction on the two dimensional canvas to the nearest
- *  snap target.
- *
- *  constrainedSnapReturnByRef() is equal in snapping behavior to
- *  constrainedSnap(), but the former returns the snapped point trough the referenced
- *  parameter p. This parameter p initially contains the position of the snap
- *  source and will be overwritten by the target position if snapping has occurred.
- *  This makes snapping transparent to the calling code. If this is not desired
- *  because either the calling code must know whether snapping has occurred, or
- *  because the original position should not be touched, then constrainedSnap() should
- *  be called instead. If there's nothing to snap to or if snapping has been disabled,
- *  then this method will still apply the constraint (but without snapping)
- *
- *  PS:
- *  1) SnapManager::setup() must have been called before calling this method,
- *  but only once for a set of points
- *  2) Only to be used when a single source point is to be snapped; it assumes
- *  that source_num = 0, which is inefficient when snapping sets our source points
-
- *
- *  @param p Current position of the snap source; will be overwritten by the position of the snap target if snapping has occurred
- *  @param source_type Detailed description of the source type, will be used by the snap indicator
- *  @param constraint The direction or line along which snapping must occur
- *  @param bbox_to_snap Bounding box hulling the set of points, all from the same selection and having the same transformation
- */
 void SnapManager::constrainedSnapReturnByRef(Geom::Point &p,
                                              Inkscape::SnapSourceType const source_type,
                                              Inkscape::Snapper::SnapConstraint const &constraint,
@@ -348,23 +218,6 @@ void SnapManager::constrainedSnapReturnByRef(Geom::Point &p,
     p = s.getPoint(); // If we didn't snap, then we will return the point projected onto the constraint
 }
 
-/**
- *  Try to snap a point along a constraint line to grids, guides or objects.
- *
- *  Try to snap a point to grids, guides or objects, in only one degree-of-freedom,
- *  i.e. snap in a specific direction on the two dimensional canvas to the nearest
- *  snap target. constrainedSnap is equal in snapping behavior to
- *  constrainedSnapReturnByRef(). Please read the comments of the latter for more details.
- *
- *  PS: SnapManager::setup() must have been called before calling this method,
- *  but only once for a set of points
- *  PS: If there's nothing to snap to or if snapping has been disabled, then this
- *  method will still apply the constraint (but without snapping)
- *
- *  @param p Source point to be snapped
- *  @param constraint The direction or line along which snapping must occur
- *  @param bbox_to_snap Bounding box hulling the set of points, all from the same selection and having the same transformation
- */
 Inkscape::SnappedPoint SnapManager::constrainedSnap(Inkscape::SnapCandidatePoint const &p,
                                                     Inkscape::Snapper::SnapConstraint const &constraint,
                                                     Geom::OptRect const &bbox_to_snap) const
@@ -508,18 +361,6 @@ Inkscape::SnappedPoint SnapManager::multipleConstrainedSnaps(Inkscape::SnapCandi
     return no_snap;
 }
 
-/**
- *  Try to snap a point to something at a specific angle.
- *
- *  When drawing a straight line or modifying a gradient, it will snap to specific angle increments
- *  if CTRL is being pressed. This method will enforce this angular constraint (even if there is nothing
- *  to snap to)
- *
- *  @param p Source point to be snapped
- *  @param p_ref Optional original point, relative to which the angle should be calculated. If empty then
- *  the angle will be calculated relative to the y-axis
- *  @param snaps Number of angular increments per PI radians; E.g. if snaps = 2 then we will snap every PI/2 = 90 degrees
- */
 Inkscape::SnappedPoint SnapManager::constrainedAngularSnap(Inkscape::SnapCandidatePoint const &p,
                                                             boost::optional<Geom::Point> const &p_ref,
                                                             Geom::Point const &o,
@@ -556,14 +397,6 @@ Inkscape::SnappedPoint SnapManager::constrainedAngularSnap(Inkscape::SnapCandida
     return sp;
 }
 
-/**
- *  Wrapper method to make snapping of the guide origin a bit easier (i.e. simplifies the calling code).
- *
- *  PS: SnapManager::setup() must have been called before calling this method,
- *
- *  @param p Current position of the point on the guide that is to be snapped; will be overwritten by the position of the snap target if snapping has occurred
- *  @param guide_normal Vector normal to the guide line
- */
 void SnapManager::guideFreeSnap(Geom::Point &p, Geom::Point const &/*guide_normal*/, SPGuideDragType drag_type) const
 {
     if (!snapprefs.getSnapEnabledGlobally() || snapprefs.getSnapPostponedGlobally() || !snapprefs.isTargetSnappable(Inkscape::SNAPTARGET_GUIDE)) {
@@ -586,14 +419,6 @@ void SnapManager::guideFreeSnap(Geom::Point &p, Geom::Point const &/*guide_norma
     s.getPointIfSnapped(p);
 }
 
-/**
- *  Wrapper method to make snapping of the guide origin a bit easier (i.e. simplifies the calling code).
- *
- *  PS: SnapManager::setup() must have been called before calling this method,
- *
- *  @param p Current position of the point on the guide that is to be snapped; will be overwritten by the position of the snap target if snapping has occurred
- *  @param guide_normal Vector normal to the guide line
- */
 void SnapManager::guideConstrainedSnap(Geom::Point &p, SPGuide const &guideline) const
 {
     if (!snapprefs.getSnapEnabledGlobally() || snapprefs.getSnapPostponedGlobally() || !snapprefs.isTargetSnappable(Inkscape::SNAPTARGET_GUIDE)) {
@@ -614,32 +439,6 @@ void SnapManager::guideConstrainedSnap(Geom::Point &p, SPGuide const &guideline)
     s.getPointIfSnapped(p);
 }
 
-/**
- *  Method for snapping sets of points while they are being transformed.
- *
- *  Method for snapping sets of points while they are being transformed, when using
- *  for example the selector tool. This method is for internal use only, and should
- *  not have to be called directly. Use freeSnapTransalation(), constrainedSnapScale(),
- *  etc. instead.
- *
- *  This is what is being done in this method: transform each point, find out whether
- *  a free snap or constrained snap is more appropriate, do the snapping, calculate
- *  some metrics to quantify the snap "distance", and see if it's better than the
- *  previous snap. Finally, the best ("nearest") snap from all these points is returned.
- *  If no snap has occurred and we're asked for a constrained snap then the constraint
- *  will be applied nevertheless
- *
- *  @param points Collection of points to snap (snap sources), at their untransformed position, all points undergoing the same transformation. Paired with an identifier of the type of the snap source.
- *  @param pointer Location of the mouse pointer at the time dragging started (i.e. when the selection was still untransformed).
- *  @param constrained true if the snap is constrained, e.g. for stretching or for purely horizontal translation.
- *  @param constraint The direction or line along which snapping must occur, 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 to which the transformation applies, if applicable.
- *  @param uniform true if the transformation should be uniform; only applicable for stretching and scaling.
- *  @return An instance of the SnappedPoint class, which holds data on the snap source, snap target, and various metrics.
- */
 Inkscape::SnappedPoint SnapManager::_snapTransformed(
     std::vector<Inkscape::SnapCandidatePoint> const &points,
     Geom::Point const &pointer,
@@ -930,14 +729,6 @@ Inkscape::SnappedPoint SnapManager::_snapTransformed(
 }
 
 
-/**
- *  Apply a translation to a set of points and try to snap freely in 2 degrees-of-freedom.
- *
- *  @param p Collection of points to snap (snap sources), at their untransformed position, all points undergoing the same transformation. Paired with an identifier of the type of the snap source.
- *  @param pointer Location of the mouse pointer at the time dragging started (i.e. when the selection was still untransformed).
- *  @param tr Proposed translation; the final translation can only be calculated after snapping has occurred
- *  @return An instance of the SnappedPoint class, which holds data on the snap source, snap target, and various metrics.
- */
 Inkscape::SnappedPoint SnapManager::freeSnapTranslate(std::vector<Inkscape::SnapCandidatePoint> const &p,
                                                         Geom::Point const &pointer,
                                                         Geom::Point const &tr)
@@ -951,15 +742,6 @@ Inkscape::SnappedPoint SnapManager::freeSnapTranslate(std::vector<Inkscape::Snap
     return result;
 }
 
-/**
- *  Apply a translation to a set of points and try to snap along a constraint.
- *
- *  @param p Collection of points to snap (snap sources), at their untransformed position, all points undergoing the same transformation. Paired with an identifier of the type of the snap source.
- *  @param pointer Location of the mouse pointer at the time dragging started (i.e. when the selection was still untransformed).
- *  @param constraint The direction or line along which snapping must occur.
- *  @param tr Proposed translation; the final translation can only be calculated after snapping has occurred.
- *  @return An instance of the SnappedPoint class, which holds data on the snap source, snap target, and various metrics.
- */
 Inkscape::SnappedPoint SnapManager::constrainedSnapTranslate(std::vector<Inkscape::SnapCandidatePoint> const &p,
                                                                Geom::Point const &pointer,
                                                                Inkscape::Snapper::SnapConstraint const &constraint,
@@ -975,15 +757,6 @@ Inkscape::SnappedPoint SnapManager::constrainedSnapTranslate(std::vector<Inkscap
 }
 
 
-/**
- *  Apply a scaling to a set of points and try to snap freely in 2 degrees-of-freedom.
- *
- *  @param p Collection of points to snap (snap sources), at their untransformed position, all points undergoing the same transformation. Paired with an identifier of the type of the snap source.
- *  @param pointer Location of the mouse pointer at the time dragging started (i.e. when the selection was still untransformed).
- *  @param s Proposed scaling; the final scaling can only be calculated after snapping has occurred
- *  @param o Origin of the scaling
- *  @return An instance of the SnappedPoint class, which holds data on the snap source, snap target, and various metrics.
- */
 Inkscape::SnappedPoint SnapManager::freeSnapScale(std::vector<Inkscape::SnapCandidatePoint> const &p,
                                                   Geom::Point const &pointer,
                                                   Geom::Scale const &s,
@@ -999,15 +772,6 @@ Inkscape::SnappedPoint SnapManager::freeSnapScale(std::vector<Inkscape::SnapCand
 }
 
 
-/**
- *  Apply a scaling to a set of points and snap such that the aspect ratio of the selection is preserved.
- *
- *  @param p Collection of points to snap (snap sources), at their untransformed position, all points undergoing the same transformation. Paired with an identifier of the type of the snap source.
- *  @param pointer Location of the mouse pointer at the time dragging started (i.e. when the selection was still untransformed).
- *  @param s Proposed scaling; the final scaling can only be calculated after snapping has occurred
- *  @param o Origin of the scaling
- *  @return An instance of the SnappedPoint class, which holds data on the snap source, snap target, and various metrics.
- */
 Inkscape::SnappedPoint SnapManager::constrainedSnapScale(std::vector<Inkscape::SnapCandidatePoint> const &p,
                                                          Geom::Point const &pointer,
                                                          Geom::Scale const &s,
@@ -1023,17 +787,6 @@ Inkscape::SnappedPoint SnapManager::constrainedSnapScale(std::vector<Inkscape::S
     return result;
 }
 
-/**
- *  Apply a stretch to a set of points and snap such that the direction of the stretch is preserved.
- *
- *  @param p Collection of points to snap (snap sources), at their untransformed position, all points undergoing the same transformation. Paired with an identifier of the type of the snap source.
- *  @param pointer Location of the mouse pointer at the time dragging started (i.e. when the selection was still untransformed).
- *  @param s Proposed stretch; the final stretch can only be calculated after snapping has occurred
- *  @param o Origin of the stretching
- *  @param d Dimension in which to apply proposed stretch.
- *  @param u true if the stretch should be uniform (i.e. to be applied equally in both dimensions)
- *  @return An instance of the SnappedPoint class, which holds data on the snap source, snap target, and various metrics.
- */
 Inkscape::SnappedPoint SnapManager::constrainedSnapStretch(std::vector<Inkscape::SnapCandidatePoint> const &p,
                                                             Geom::Point const &pointer,
                                                             Geom::Coord const &s,
@@ -1050,17 +803,6 @@ Inkscape::SnappedPoint SnapManager::constrainedSnapStretch(std::vector<Inkscape:
     return result;
 }
 
-/**
- *  Apply a skew to a set of points and snap such that the direction of the skew is preserved.
- *
- *  @param p Collection of points to snap (snap sources), at their untransformed position, all points undergoing the same transformation. Paired with an identifier of the type of the snap source.
- *  @param pointer Location of the mouse pointer at the time dragging started (i.e. when the selection was still untransformed).
- *  @param constraint The direction or line along which snapping must occur.
- *  @param s Proposed skew; the final skew can only be calculated after snapping has occurred
- *  @param o Origin of the proposed skew
- *  @param d Dimension in which to apply proposed skew.
- *  @return An instance of the SnappedPoint class, which holds data on the snap source, snap target, and various metrics.
- */
 Inkscape::SnappedPoint SnapManager::constrainedSnapSkew(std::vector<Inkscape::SnapCandidatePoint> const &p,
                                                  Geom::Point const &pointer,
                                                  Inkscape::Snapper::SnapConstraint const &constraint,
@@ -1088,15 +830,6 @@ Inkscape::SnappedPoint SnapManager::constrainedSnapSkew(std::vector<Inkscape::Sn
     return result;
 }
 
-/**
- *  Apply a rotation to a set of points and snap, without scaling.
- *
- *  @param p Collection of points to snap (snap sources), at their untransformed position, all points undergoing the same transformation. Paired with an identifier of the type of the snap source.
- *  @param pointer Location of the mouse pointer at the time dragging started (i.e. when the selection was still untransformed).
- *  @param angle Proposed rotation (in radians); the final rotation can only be calculated after snapping has occurred
- *  @param o Origin of the rotation
- *  @return An instance of the SnappedPoint class, which holds data on the snap source, snap target, and various metrics.
- */
 Inkscape::SnappedPoint SnapManager::constrainedSnapRotate(std::vector<Inkscape::SnapCandidatePoint> const &p,
                                                     Geom::Point const &pointer,
                                                     Geom::Coord const &angle,
@@ -1118,16 +851,6 @@ Inkscape::SnappedPoint SnapManager::constrainedSnapRotate(std::vector<Inkscape::
 
 }
 
-/**
- * Given a set of possible snap targets, find the best target (which is not necessarily
- * also the nearest target), and show the snap indicator if requested.
- *
- * @param p Source point to be snapped
- * @param isr A structure holding all snap targets that have been found so far
- * @param constrained True if the snap is constrained, e.g. for stretching or for purely horizontal translation.
- * @param allowOffScreen If true, then snapping to points which are off the screen is allowed (needed for example when pasting to the grid)
- * @return An instance of the SnappedPoint class, which holds data on the snap source, snap target, and various metrics
- */
 Inkscape::SnappedPoint SnapManager::findBestSnap(Inkscape::SnapCandidatePoint const &p,
                                                  IntermSnapResults const &isr,
                                                  bool constrained,
@@ -1273,7 +996,6 @@ Inkscape::SnappedPoint SnapManager::findBestSnap(Inkscape::SnapCandidatePoint co
     return bestSnappedPoint;
 }
 
-/// Convenience shortcut when there is only one item to ignore
 void SnapManager::setup(SPDesktop const *desktop,
                         bool snapindicator,
                         SPItem const *item_to_ignore,
@@ -1293,21 +1015,6 @@ void SnapManager::setup(SPDesktop const *desktop,
     _rotation_center_source_items = NULL;
 }
 
-/**
- * Prepare the snap manager for the actual snapping, which includes building a list of snap targets
- * to ignore and toggling the snap indicator.
- *
- * There are two overloaded setup() methods, of which the other one only allows for a single item to be ignored
- * whereas this one will take a list of items to ignore
- *
- * @param desktop Reference to the desktop to which this snap manager is attached
- * @param snapindicator If true then a snap indicator will be displayed automatically (when enabled in the preferences)
- * @param items_to_ignore These items will not be snapped to, e.g. the items that are currently being dragged. This avoids "self-snapping"
- * @param unselected_nodes Stationary nodes of the path that is currently being edited in the node tool and
- * that can be snapped too. Nodes not in this list will not be snapped to, to avoid "self-snapping". Of each
- * unselected node both the position (Geom::Point) and the type (Inkscape::SnapTargetType) will be stored
- * @param guide_to_ignore Guide that is currently being dragged and should not be snapped to
- */
 void SnapManager::setup(SPDesktop const *desktop,
                         bool snapindicator,
                         std::vector<SPItem const *> &items_to_ignore,
@@ -1356,17 +1063,6 @@ SPDocument *SnapManager::getDocument() const
     return _named_view->document;
 }
 
-/**
- * Takes an untransformed point, applies the given transformation, and returns the transformed point. Eliminates lots of duplicated code.
- *
- * @param p The untransformed position of the point, paired with an identifier of the type of the snap source.
- * @param transformation_type Type of transformation to apply.
- * @param transformation Mathematical description of the transformation; details depend on the type.
- * @param origin Origin of the transformation, if applicable.
- * @param dim Dimension to which the transformation applies, if applicable.
- * @param uniform true if the transformation should be uniform; only applicable for stretching and scaling.
- * @return The position of the point after transformation
- */
 Geom::Point SnapManager::_transformPoint(Inkscape::SnapCandidatePoint const &p,
                                         Transformation const transformation_type,
                                         Geom::Point const &transformation,
@@ -1413,12 +1109,6 @@ Geom::Point SnapManager::_transformPoint(Inkscape::SnapCandidatePoint const &p,
     return transformed;
 }
 
-/**
- * Mark the location of the snap source (not the snap target!) on the canvas by drawing a symbol.
- *
- * @param point_type Category of points to which the source point belongs: node, guide or bounding box
- * @param p The transformed position of the source point, paired with an identifier of the type of the snap source.
- */
 void SnapManager::_displaySnapsource(Inkscape::SnapCandidatePoint const &p) const {
 
     Inkscape::Preferences *prefs = Inkscape::Preferences::get();
diff --git a/src/snap.h b/src/snap.h
index 41cbd0a02..fffbbdf6a 100644
--- a/src/snap.h
+++ b/src/snap.h
@@ -1,7 +1,6 @@
-/**
- * \file snap.h
- * \brief Per-desktop object that handles snapping queries
- *//*
+/*
+ * Per-desktop object that handles snapping queries.
+ *
  * Authors:
  *   Lauris Kaplinski <lauris@kaplinski.com>
  *   Frank Felfe <innerspace@iname.com>
@@ -23,7 +22,7 @@
 #include "object-snapper.h"
 #include "snap-preferences.h"
 
-/* Guides */
+// Guides
 enum SPGuideDragType { // used both here and in desktop-events.cpp
     SP_DRAG_TRANSLATE,
     SP_DRAG_ROTATE,
@@ -34,8 +33,9 @@ enum SPGuideDragType { // used both here and in desktop-events.cpp
 class SPGuide;
 class SPNamedView;
 
-/// Class to coordinate snapping operations
 /**
+ * Class to coordinate snapping operations.
+ *
  * The SnapManager class handles most (if not all) of the interfacing of the snapping mechanisms
  * with the other parts of the code base. It stores the references to the various types of snappers
  * for grid, guides and objects, and it stores most of the snapping preferences. Besides that
@@ -63,7 +63,6 @@ class SPNamedView;
  * write snapping code directly in your control point's dragged handler as if there was
  * no timeout.
  */
-
 class SnapManager
 {
 public:
@@ -75,19 +74,56 @@ public:
         ROTATE
     };
 
+    /**
+     * Construct a SnapManager for a SPNamedView.
+     *
+     * @param v 'Owning' SPNamedView.
+     */
     SnapManager(SPNamedView const *v);
 
     typedef std::list<const Inkscape::Snapper*> SnapperList;
 
+    /**
+     * Return true if any snapping might occur, whether its to grids, guides or objects.
+     *
+     * Each snapper instance handles its own snapping target, e.g. grids, guides or
+     * objects. This method iterates through all these snapper instances and returns
+     * true if any of the snappers might possible snap, considering only the relevant
+     * snapping preferences.
+     *
+     * @return true if one of the snappers will try to snap to something.
+     */
     bool someSnapperMightSnap() const;
+
+    /**
+     * @return true if one of the grids might be snapped to.
+     */
     bool gridSnapperMightSnap() const;
 
+    /**
+     * Convenience shortcut when there is only one item to ignore.
+     */
     void setup(SPDesktop const *desktop,
             bool snapindicator = true,
             SPItem const *item_to_ignore = NULL,
             std::vector<Inkscape::SnapCandidatePoint> *unselected_nodes = NULL,
             SPGuide *guide_to_ignore = NULL);
 
+    /**
+     * Prepare the snap manager for the actual snapping, which includes building a list of snap targets
+     * to ignore and toggling the snap indicator.
+     *
+     * There are two overloaded setup() methods, of which the other one only allows for a single item to be ignored
+     * whereas this one will take a list of items to ignore
+     *
+     * @param desktop Reference to the desktop to which this snap manager is attached.
+     * @param snapindicator If true then a snap indicator will be displayed automatically (when enabled in the preferences).
+     * @param items_to_ignore These items will not be snapped to, e.g. the items that are currently being dragged. This avoids "self-snapping".
+     * @param unselected_nodes Stationary nodes of the path that is currently being edited in the node tool and
+     * that can be snapped too. Nodes not in this list will not be snapped to, to avoid "self-snapping". Of each
+     * unselected node both the position (Geom::Point) and the type (Inkscape::SnapTargetType) will be stored.
+     * @param guide_to_ignore Guide that is currently being dragged and should not be snapped to.
+     */
     void setup(SPDesktop const *desktop,
                bool snapindicator,
                std::vector<SPItem const *> &items_to_ignore,
@@ -113,6 +149,31 @@ public:
 
     // freeSnapReturnByRef() is preferred over freeSnap(), because it only returns a
     // point if snapping has occurred (by overwriting p); otherwise p is untouched
+
+    /**
+     * Try to snap a point to grids, guides or objects.
+     *
+     * Try to snap a point to grids, guides or objects, in two degrees-of-freedom,
+     * i.e. snap in any direction on the two dimensional canvas to the nearest
+     * snap target. freeSnapReturnByRef() is equal in snapping behavior to
+     * freeSnap(), but the former returns the snapped point trough the referenced
+     * parameter p. This parameter p initially contains the position of the snap
+     * source and will we overwritten by the target position if snapping has occurred.
+     * This makes snapping transparent to the calling code. If this is not desired
+     * because either the calling code must know whether snapping has occurred, or
+     * because the original position should not be touched, then freeSnap() should be
+     * called instead.
+     *
+     * PS:
+     * 1) SnapManager::setup() must have been called before calling this method,
+     * but only once for a set of points
+     * 2) Only to be used when a single source point is to be snapped; it assumes
+     * that source_num = 0, which is inefficient when snapping sets our source points
+     *
+     * @param p Current position of the snap source; will be overwritten by the position of the snap target if snapping has occurred.
+     * @param source_type Detailed description of the source type, will be used by the snap indicator.
+     * @param bbox_to_snap Bounding box hulling the set of points, all from the same selection and having the same transformation.
+     */
     void freeSnapReturnByRef(Geom::Point &p,
                              Inkscape::SnapSourceType const source_type,
                              Geom::OptRect const &bbox_to_snap = Geom::OptRect()) const;
@@ -121,20 +182,100 @@ public:
                              Inkscape::SnapSourceType const source_type,
                              boost::optional<Geom::Point> &starting_point) const;
 
+    /**
+     * Try to snap a point to grids, guides or objects.
+     *
+     * Try to snap a point to grids, guides or objects, in two degrees-of-freedom,
+     * i.e. snap in any direction on the two dimensional canvas to the nearest
+     * snap target. freeSnap() is equal in snapping behavior to
+     * freeSnapReturnByRef(). Please read the comments of the latter for more details
+     *
+     * PS: SnapManager::setup() must have been called before calling this method,
+     * but only once for a set of points
+     *
+     * @param p Source point to be snapped.
+     * @param bbox_to_snap Bounding box hulling the set of points, all from the same selection and having the same transformation.
+     * @return An instance of the SnappedPoint class, which holds data on the snap source, snap target, and various metrics.
+     */
     Inkscape::SnappedPoint freeSnap(Inkscape::SnapCandidatePoint const &p,
                                     Geom::OptRect const &bbox_to_snap = Geom::OptRect() ) const;
 
     void preSnap(Inkscape::SnapCandidatePoint const &p);
 
+    /**
+     * Snap to the closest multiple of a grid pitch.
+     *
+     * When pasting, we would like to snap to the grid. Problem is that we don't know which
+     * nodes were aligned to the grid at the time of copying, so we don't know which nodes
+     * to snap. If we'd snap an unaligned node to the grid, previously aligned nodes would
+     * become unaligned. That's undesirable. Instead we will make sure that the offset
+     * between the source and its pasted copy is a multiple of the grid pitch. If the source
+     * was aligned, then the copy will therefore also be aligned.
+     *
+     * PS: Whether we really find a multiple also depends on the snapping range! Most users
+     * will have "always snap" enabled though, in which case a multiple will always be found.
+     * PS2: When multiple grids are present then the result will become ambiguous. There is no
+     * way to control to which grid this method will snap.
+     *
+     * @param t Vector that represents the offset of the pasted copy with respect to the original.
+     * @return Offset vector after snapping to the closest multiple of a grid pitch.
+     */
     Geom::Point multipleOfGridPitch(Geom::Point const &t, Geom::Point const &origin);
 
     // constrainedSnapReturnByRef() is preferred over constrainedSnap(), because it only returns a
     // point, by overwriting p, if snapping has occurred; otherwise p is untouched
+
+    /**
+     * Try to snap a point along a constraint line to grids, guides or objects.
+     *
+     * Try to snap a point to grids, guides or objects, in only one degree-of-freedom,
+     * i.e. snap in a specific direction on the two dimensional canvas to the nearest
+     * snap target.
+     *
+     * constrainedSnapReturnByRef() is equal in snapping behavior to
+     * constrainedSnap(), but the former returns the snapped point trough the referenced
+     * parameter p. This parameter p initially contains the position of the snap
+     * source and will be overwritten by the target position if snapping has occurred.
+     * This makes snapping transparent to the calling code. If this is not desired
+     * because either the calling code must know whether snapping has occurred, or
+     * because the original position should not be touched, then constrainedSnap() should
+     * be called instead. If there's nothing to snap to or if snapping has been disabled,
+     * then this method will still apply the constraint (but without snapping)
+     *
+     * PS:
+     * 1) SnapManager::setup() must have been called before calling this method,
+     * but only once for a set of points
+     * 2) Only to be used when a single source point is to be snapped; it assumes
+     * that source_num = 0, which is inefficient when snapping sets our source points
+
+     *
+     * @param p Current position of the snap source; will be overwritten by the position of the snap target if snapping has occurred.
+     * @param source_type Detailed description of the source type, will be used by the snap indicator.
+     * @param constraint The direction or line along which snapping must occur.
+     * @param bbox_to_snap Bounding box hulling the set of points, all from the same selection and having the same transformation.
+     */
     void constrainedSnapReturnByRef(Geom::Point &p,
                                     Inkscape::SnapSourceType const source_type,
                                     Inkscape::Snapper::SnapConstraint const &constraint,
                                     Geom::OptRect const &bbox_to_snap = Geom::OptRect()) const;
 
+    /**
+     * Try to snap a point along a constraint line to grids, guides or objects.
+     *
+     * Try to snap a point to grids, guides or objects, in only one degree-of-freedom,
+     * i.e. snap in a specific direction on the two dimensional canvas to the nearest
+     * snap target. constrainedSnap is equal in snapping behavior to
+     * constrainedSnapReturnByRef(). Please read the comments of the latter for more details.
+     *
+     * PS: SnapManager::setup() must have been called before calling this method,
+     * but only once for a set of points
+     * PS: If there's nothing to snap to or if snapping has been disabled, then this
+     * method will still apply the constraint (but without snapping)
+     *
+     * @param p Source point to be snapped.
+     * @param constraint The direction or line along which snapping must occur.
+     * @param bbox_to_snap Bounding box hulling the set of points, all from the same selection and having the same transformation.
+     */
     Inkscape::SnappedPoint constrainedSnap(Inkscape::SnapCandidatePoint const &p,
                                            Inkscape::Snapper::SnapConstraint const &constraint,
                                            Geom::OptRect const &bbox_to_snap = Geom::OptRect()) const;
@@ -144,33 +285,109 @@ public:
                                                     bool dont_snap = false,
                                                     Geom::OptRect const &bbox_to_snap = Geom::OptRect()) const;
 
+    /**
+     * Try to snap a point to something at a specific angle.
+     *
+     * When drawing a straight line or modifying a gradient, it will snap to specific angle increments
+     * if CTRL is being pressed. This method will enforce this angular constraint (even if there is nothing
+     * to snap to)
+     *
+     * @param p Source point to be snapped.
+     * @param p_ref Optional original point, relative to which the angle should be calculated. If empty then
+     * the angle will be calculated relative to the y-axis.
+     * @param snaps Number of angular increments per PI radians; E.g. if snaps = 2 then we will snap every PI/2 = 90 degrees.
+     */
     Inkscape::SnappedPoint constrainedAngularSnap(Inkscape::SnapCandidatePoint const &p,
                                                     boost::optional<Geom::Point> const &p_ref,
                                                     Geom::Point const &o,
                                                     unsigned const snaps) const;
 
+    /**
+     * Wrapper method to make snapping of the guide origin a bit easier (i.e. simplifies the calling code).
+     *
+     * PS: SnapManager::setup() must have been called before calling this method,
+     *
+     * @param p Current position of the point on the guide that is to be snapped; will be overwritten by the position of the snap target if snapping has occurred.
+     * @param guide_normal Vector normal to the guide line.
+     */
     void guideFreeSnap(Geom::Point &p, Geom::Point const &guide_normal, SPGuideDragType drag_type) const;
+
+    /**
+     * Wrapper method to make snapping of the guide origin a bit easier (i.e. simplifies the calling code).
+     *
+     * PS: SnapManager::setup() must have been called before calling this method,
+     *
+     * @param p Current position of the point on the guide that is to be snapped; will be overwritten by the position of the snap target if snapping has occurred.
+     * @param guide_normal Vector normal to the guide line.
+     */
     void guideConstrainedSnap(Geom::Point &p, SPGuide const &guideline) const;
 
+
+    /**
+     * Apply a translation to a set of points and try to snap freely in 2 degrees-of-freedom.
+     *
+     * @param p Collection of points to snap (snap sources), at their untransformed position, all points undergoing the same transformation. Paired with an identifier of the type of the snap source.
+     * @param pointer Location of the mouse pointer at the time dragging started (i.e. when the selection was still untransformed).
+     * @param tr Proposed translation; the final translation can only be calculated after snapping has occurred.
+     * @return An instance of the SnappedPoint class, which holds data on the snap source, snap target, and various metrics.
+     */
     Inkscape::SnappedPoint freeSnapTranslate(std::vector<Inkscape::SnapCandidatePoint> const &p,
                                                Geom::Point const &pointer,
                                                Geom::Point const &tr);
 
+    /**
+     * Apply a translation to a set of points and try to snap along a constraint.
+     *
+     * @param p Collection of points to snap (snap sources), at their untransformed position, all points undergoing the same transformation. Paired with an identifier of the type of the snap source.
+     * @param pointer Location of the mouse pointer at the time dragging started (i.e. when the selection was still untransformed).
+     * @param constraint The direction or line along which snapping must occur.
+     * @param tr Proposed translation; the final translation can only be calculated after snapping has occurred.
+     * @return An instance of the SnappedPoint class, which holds data on the snap source, snap target, and various metrics.
+     */
     Inkscape::SnappedPoint constrainedSnapTranslate(std::vector<Inkscape::SnapCandidatePoint> const &p,
                                                       Geom::Point const &pointer,
                                                       Inkscape::Snapper::SnapConstraint const &constraint,
                                                       Geom::Point const &tr);
 
+    /**
+     * Apply a scaling to a set of points and try to snap freely in 2 degrees-of-freedom.
+     *
+     * @param p Collection of points to snap (snap sources), at their untransformed position, all points undergoing the same transformation. Paired with an identifier of the type of the snap source.
+     * @param pointer Location of the mouse pointer at the time dragging started (i.e. when the selection was still untransformed).
+     * @param s Proposed scaling; the final scaling can only be calculated after snapping has occurred.
+     * @param o Origin of the scaling.
+     * @return An instance of the SnappedPoint class, which holds data on the snap source, snap target, and various metrics.
+     */
     Inkscape::SnappedPoint freeSnapScale(std::vector<Inkscape::SnapCandidatePoint> const &p,
                                          Geom::Point const &pointer,
                                          Geom::Scale const &s,
                                          Geom::Point const &o);
 
+    /**
+     * Apply a scaling to a set of points and snap such that the aspect ratio of the selection is preserved.
+     *
+     * @param p Collection of points to snap (snap sources), at their untransformed position, all points undergoing the same transformation. Paired with an identifier of the type of the snap source.
+     * @param pointer Location of the mouse pointer at the time dragging started (i.e. when the selection was still untransformed).
+     * @param s Proposed scaling; the final scaling can only be calculated after snapping has occurred.
+     * @param o Origin of the scaling.
+     * @return An instance of the SnappedPoint class, which holds data on the snap source, snap target, and various metrics.
+     */
     Inkscape::SnappedPoint constrainedSnapScale(std::vector<Inkscape::SnapCandidatePoint> const &p,
                                                 Geom::Point const &pointer,
                                                 Geom::Scale const &s,
                                                 Geom::Point const &o);
 
+    /**
+     * Apply a stretch to a set of points and snap such that the direction of the stretch is preserved.
+     *
+     * @param p Collection of points to snap (snap sources), at their untransformed position, all points undergoing the same transformation. Paired with an identifier of the type of the snap source.
+     * @param pointer Location of the mouse pointer at the time dragging started (i.e. when the selection was still untransformed).
+     * @param s Proposed stretch; the final stretch can only be calculated after snapping has occurred.
+     * @param o Origin of the stretching.
+     * @param d Dimension in which to apply proposed stretch.
+     * @param u true if the stretch should be uniform (i.e. to be applied equally in both dimensions).
+     * @return An instance of the SnappedPoint class, which holds data on the snap source, snap target, and various metrics.
+     */
     Inkscape::SnappedPoint constrainedSnapStretch(std::vector<Inkscape::SnapCandidatePoint> const &p,
                                                   Geom::Point const &pointer,
                                                   Geom::Coord const &s,
@@ -178,6 +395,17 @@ public:
                                                   Geom::Dim2 d,
                                                   bool uniform);
 
+    /**
+     * Apply a skew to a set of points and snap such that the direction of the skew is preserved.
+     *
+     * @param p Collection of points to snap (snap sources), at their untransformed position, all points undergoing the same transformation. Paired with an identifier of the type of the snap source.
+     * @param pointer Location of the mouse pointer at the time dragging started (i.e. when the selection was still untransformed).
+     * @param constraint The direction or line along which snapping must occur.
+     * @param s Proposed skew; the final skew can only be calculated after snapping has occurred.
+     * @param o Origin of the proposed skew.
+     * @param d Dimension in which to apply proposed skew.
+     * @return An instance of the SnappedPoint class, which holds data on the snap source, snap target, and various metrics.
+     */
     Inkscape::SnappedPoint constrainedSnapSkew(std::vector<Inkscape::SnapCandidatePoint> const &p,
                                                Geom::Point const &pointer,
                                                Inkscape::Snapper::SnapConstraint const &constraint,
@@ -185,6 +413,15 @@ public:
                                                Geom::Point const &o,
                                                Geom::Dim2 d);
 
+    /**
+     * Apply a rotation to a set of points and snap, without scaling.
+     *
+     * @param p Collection of points to snap (snap sources), at their untransformed position, all points undergoing the same transformation. Paired with an identifier of the type of the snap source.
+     * @param pointer Location of the mouse pointer at the time dragging started (i.e. when the selection was still untransformed).
+     * @param angle Proposed rotation (in radians); the final rotation can only be calculated after snapping has occurred.
+     * @param o Origin of the rotation.
+     * @return An instance of the SnappedPoint class, which holds data on the snap source, snap target, and various metrics.
+     */
     Inkscape::SnappedPoint constrainedSnapRotate(std::vector<Inkscape::SnapCandidatePoint> const &p,
                                                     Geom::Point const &pointer,
                                                     Geom::Coord const &angle,
@@ -194,7 +431,30 @@ public:
     Inkscape::ObjectSnapper object;    ///< snapper to other objects
     Inkscape::SnapPreferences snapprefs;
 
+    /**
+     * Return a list of snappers.
+     *
+     * Inkscape snaps to objects, grids, and guides. For each of these snap targets a
+     * separate class is used, which has been derived from the base Snapper class. The
+     * getSnappers() method returns a list of pointers to instances of this class. This
+     * list contains exactly one instance of the guide snapper and of the object snapper
+     * class, but any number of grid snappers (because each grid has its own snapper
+     * instance)
+     *
+     * @return List of snappers that we use.
+     */
     SnapperList getSnappers() const;
+
+    /**
+     * Return a list of gridsnappers.
+     *
+     * Each grid has its own instance of the snapper class. This way snapping can
+     * be enabled per grid individually. A list will be returned containing the
+     * pointers to these instances, but only for grids that are being displayed
+     * and for which snapping is enabled.
+     *
+     * @return List of gridsnappers that we use.
+     */
     SnapperList getGridSnappers() const;
 
     SPDesktop const *getDesktop() const {return _desktop;}
@@ -204,7 +464,18 @@ public:
 
     bool getSnapIndicator() const {return _snapindicator;}
 
+    /**
+     * Given a set of possible snap targets, find the best target (which is not necessarily
+     * also the nearest target), and show the snap indicator if requested.
+     *
+     * @param p Source point to be snapped.
+     * @param isr A structure holding all snap targets that have been found so far.
+     * @param constrained True if the snap is constrained, e.g. for stretching or for purely horizontal translation.
+     * @param allowOffScreen If true, then snapping to points which are off the screen is allowed (needed for example when pasting to the grid).
+     * @return An instance of the SnappedPoint class, which holds data on the snap source, snap target, and various metrics.
+     */
     Inkscape::SnappedPoint findBestSnap(Inkscape::SnapCandidatePoint const &p, IntermSnapResults const &isr, bool constrained, bool allowOffScreen = false) const;
+
     void keepClosestPointOnly(std::vector<Inkscape::SnapCandidatePoint> &points, const Geom::Point &reference) const;
 
 protected:
@@ -218,6 +489,32 @@ private:
     bool _snapindicator; ///< When true, an indicator will be drawn at the position that was being snapped to
     std::vector<Inkscape::SnapCandidatePoint> *_unselected_nodes; ///< Nodes of the path that is currently being edited and which have not been selected and which will therefore be stationary. Only these nodes will be considered for snapping to. Of each unselected node both the position (Geom::Point) and the type (Inkscape::SnapTargetType) will be stored
 
+    /**
+     * Method for snapping sets of points while they are being transformed.
+     *
+     * Method for snapping sets of points while they are being transformed, when using
+     * for example the selector tool. This method is for internal use only, and should
+     * not have to be called directly. Use freeSnapTransalation(), constrainedSnapScale(),
+     * etc. instead.
+     *
+     * This is what is being done in this method: transform each point, find out whether
+     * a free snap or constrained snap is more appropriate, do the snapping, calculate
+     * some metrics to quantify the snap "distance", and see if it's better than the
+     * previous snap. Finally, the best ("nearest") snap from all these points is returned.
+     * If no snap has occurred and we're asked for a constrained snap then the constraint
+     * will be applied nevertheless
+     *
+     * @param points Collection of points to snap (snap sources), at their untransformed position, all points undergoing the same transformation. Paired with an identifier of the type of the snap source.
+     * @param pointer Location of the mouse pointer at the time dragging started (i.e. when the selection was still untransformed).
+     * @param constrained true if the snap is constrained, e.g. for stretching or for purely horizontal translation.
+     * @param constraint The direction or line along which snapping must occur, 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 to which the transformation applies, if applicable.
+     * @param uniform true if the transformation should be uniform; only applicable for stretching and scaling.
+     * @return An instance of the SnappedPoint class, which holds data on the snap source, snap target, and various metrics.
+     */
     Inkscape::SnappedPoint _snapTransformed(std::vector<Inkscape::SnapCandidatePoint> const &points,
                                             Geom::Point const &pointer,
                                             bool constrained,
@@ -228,6 +525,17 @@ private:
                                             Geom::Dim2 dim,
                                             bool uniform);
 
+    /**
+     * Takes an untransformed point, applies the given transformation, and returns the transformed point. Eliminates lots of duplicated code.
+     *
+     * @param p The untransformed position of the point, paired with an identifier of the type of the snap source.
+     * @param transformation_type Type of transformation to apply.
+     * @param transformation Mathematical description of the transformation; details depend on the type.
+     * @param origin Origin of the transformation, if applicable.
+     * @param dim Dimension to which the transformation applies, if applicable.
+     * @param uniform true if the transformation should be uniform; only applicable for stretching and scaling.
+     * @return The position of the point after transformation.
+     */
     Geom::Point _transformPoint(Inkscape::SnapCandidatePoint const &p,
                                             Transformation const transformation_type,
                                             Geom::Point const &transformation,
@@ -235,10 +543,16 @@ private:
                                             Geom::Dim2 const dim,
                                             bool const uniform) const;
 
+    /**
+     * Mark the location of the snap source (not the snap target!) on the canvas by drawing a symbol.
+     *
+     * @param point_type Category of points to which the source point belongs: node, guide or bounding box.
+     * @param p The transformed position of the source point, paired with an identifier of the type of the snap source.
+     */
     void _displaySnapsource(Inkscape::SnapCandidatePoint const &p) const;
 };
 
-#endif /* !SEEN_SNAP_H */
+#endif // !SEEN_SNAP_H
 
 /*
   Local Variables:
diff --git a/src/sp-object.cpp b/src/sp-object.cpp
index c12b9344b..d746e278d 100644
--- a/src/sp-object.cpp
+++ b/src/sp-object.cpp
@@ -1,4 +1,4 @@
-/** \file
+/*
  * SPObject implementation.
  *
  * Authors:
@@ -14,25 +14,6 @@
  * Released under GNU GPL, read the file 'COPYING' for more information
  */
 
-/** \class SPObject
- *
- * SPObject is an abstract base class of all of the document nodes at the
- * SVG document level. Each SPObject subclass implements a certain SVG
- * element node type, or is an abstract base class for different node
- * types.  The SPObject layer is bound to the SPRepr layer, closely
- * following the SPRepr mutations via callbacks.  During creation,
- * SPObject parses and interprets all textual attributes and CSS style
- * strings of the SPRepr, and later updates the internal state whenever
- * it receives a signal about a change. The opposite is not true - there
- * are methods manipulating SPObjects directly and such changes do not
- * propagate to the SPRepr layer. This is important for implementation of
- * the undo stack, animations and other features.
- *
- * SPObjects are bound to the higher-level container SPDocument, which
- * provides document level functionality such as the undo stack,
- * dictionary and so on. Source: doc/architecture.txt
- */
-
 #include <cstring>
 #include <string>
 
@@ -75,7 +56,7 @@ using std::strstr;
                           g_print("\n"); \
                         }
 #else
-# define debug(f, a...) /**/
+# define debug(f, a...) /* */
 #endif
 
 guint update_in_progress = 0; // guard against update-during-update
@@ -121,9 +102,6 @@ public:
 
 GObjectClass * SPObjectClass::static_parent_class = 0;
 
-/**
- * Registers the SPObject class with Gdk and returns its type number.
- */
 GType SPObject::sp_object_get_type()
 {
     static GType type = 0;
@@ -143,9 +121,6 @@ GType SPObject::sp_object_get_type()
     return type;
 }
 
-/**
- * Initializes the SPObject vtable.
- */
 void SPObjectClass::sp_object_class_init(SPObjectClass *klass)
 {
     GObjectClass *object_class;
@@ -168,9 +143,6 @@ void SPObjectClass::sp_object_class_init(SPObjectClass *klass)
     klass->write = SPObject::sp_object_private_write;
 }
 
-/**
- * Callback to initialize the SPObject object.
- */
 void SPObject::sp_object_init(SPObject *object)
 {
     debug("id=%x, typename=%s",object, g_type_name_from_instance((GTypeInstance*)object));
@@ -204,9 +176,6 @@ void SPObject::sp_object_init(SPObject *object)
     object->_default_label = NULL;
 }
 
-/**
- * Callback to destroy all members and connections of object and itself.
- */
 void SPObject::sp_object_finalize(GObject *object)
 {
     SPObject *spobject = (SPObject *)object;
@@ -278,13 +247,6 @@ Inkscape::XML::Node const* SPObject::getRepr() const{
 }
 
 
-/**
- * Increase reference count of object, with possible debugging.
- *
- * \param owner If non-NULL, make debug log entry.
- * \return object, NULL is error.
- * \pre object points to real object
- */
 SPObject *sp_object_ref(SPObject *object, SPObject *owner)
 {
     g_return_val_if_fail(object != NULL, NULL);
@@ -296,14 +258,6 @@ SPObject *sp_object_ref(SPObject *object, SPObject *owner)
     return object;
 }
 
-/**
- * Decrease reference count of object, with possible debugging and
- * finalization.
- *
- * \param owner If non-NULL, make debug log entry.
- * \return always NULL
- * \pre object points to real object
- */
 SPObject *sp_object_unref(SPObject *object, SPObject *owner)
 {
     g_return_val_if_fail(object != NULL, NULL);
@@ -315,16 +269,6 @@ SPObject *sp_object_unref(SPObject *object, SPObject *owner)
     return NULL;
 }
 
-/**
- * Increase weak refcount.
- *
- * Hrefcount is used for weak references, for example, to
- * determine whether any graphical element references a certain gradient
- * node.
- * \param owner Ignored.
- * \return object, NULL is error
- * \pre object points to real object
- */
 SPObject *sp_object_href(SPObject *object, gpointer /*owner*/)
 {
     g_return_val_if_fail(object != NULL, NULL);
@@ -336,15 +280,6 @@ SPObject *sp_object_href(SPObject *object, gpointer /*owner*/)
     return object;
 }
 
-/**
- * Decrease weak refcount.
- *
- * Hrefcount is used for weak references, for example, to determine whether
- * any graphical element references a certain gradient node.
- * \param owner Ignored.
- * \return always NULL
- * \pre object points to real object and hrefcount>0
- */
 SPObject *sp_object_hunref(SPObject *object, gpointer /*owner*/)
 {
     g_return_val_if_fail(object != NULL, NULL);
@@ -357,9 +292,6 @@ SPObject *sp_object_hunref(SPObject *object, gpointer /*owner*/)
     return NULL;
 }
 
-/**
- * Adds increment to _total_hrefcount of object and its parents.
- */
 void SPObject::_updateTotalHRefCount(int increment) {
     SPObject *topmost_collectable = NULL;
     for ( SPObject *iter = this ; iter ; iter = iter->parent ) {
@@ -378,9 +310,6 @@ void SPObject::_updateTotalHRefCount(int increment) {
     }
 }
 
-/**
- * True if object is non-NULL and this is some in/direct parent of object.
- */
 bool SPObject::isAncestorOf(SPObject const *object) const {
     g_return_val_if_fail(object != NULL, false);
     object = object->parent;
@@ -401,9 +330,6 @@ bool same_objects(SPObject const &a, SPObject const &b) {
 
 }
 
-/**
- * Returns youngest object being parent to this and object.
- */
 SPObject const *SPObject::nearestCommonAncestor(SPObject const *object) const {
     g_return_val_if_fail(object != NULL, NULL);
 
@@ -423,15 +349,6 @@ SPObject const *AncestorSon(SPObject const *obj, SPObject const *ancestor) {
     return result;
 }
 
-/**
- * Compares height of objects in tree.
- *
- * Works for different-parent objects, so long as they have a common ancestor.
- * \return \verbatim
- *    0    positions are equivalent
- *    1    first object's position is greater than the second
- *   -1    first object's position is less than the second   \endverbatim
- */
 int sp_object_compare_position(SPObject const *first, SPObject const *second)
 {
     int result = 0;
@@ -458,10 +375,6 @@ int sp_object_compare_position(SPObject const *first, SPObject const *second)
 }
 
 
-/**
- * Append repr as child of this object.
- * \pre this is not a cloned object
- */
 SPObject *SPObject::appendChildRepr(Inkscape::XML::Node *repr) {
     if ( !cloned ) {
         getRepr()->appendChild(repr);
@@ -497,14 +410,10 @@ GSList *SPObject::childList(bool add_ref, Action) {
 
 }
 
-/** Gets the label property for the object or a default if no label
- *  is defined.
- */
 gchar const *SPObject::label() const {
     return _label;
 }
 
-/** Returns a default label property for the object. */
 gchar const *SPObject::defaultLabel() const {
     if (_label) {
         return _label;
@@ -520,13 +429,12 @@ gchar const *SPObject::defaultLabel() const {
     }
 }
 
-/** Sets the label property for the object */
-void SPObject::setLabel(gchar const *label) {
+void SPObject::setLabel(gchar const *label)
+{
     getRepr()->setAttribute("inkscape:label", label, false);
 }
 
 
-/** Queues the object for orphan collection */
 void SPObject::requestOrphanCollection() {
     g_return_if_fail(document != NULL);
 
@@ -563,13 +471,6 @@ void SPObject::_sendDeleteSignalRecursive() {
     }
 }
 
-/**
- * Deletes the object reference, unparenting it from its parent.
- *
- * If the \a propagate parameter is set to true, it emits a delete
- * signal.  If the \a propagate_descendants parameter is true, it
- * recursively sends the delete signal to children.
- */
 void SPObject::deleteObject(bool propagate, bool propagate_descendants)
 {
     sp_object_ref(this, NULL);
@@ -591,10 +492,6 @@ void SPObject::deleteObject(bool propagate, bool propagate_descendants)
     sp_object_unref(this, NULL);
 }
 
-/**
- * Put object into object tree, under parent, and behind prev;
- * also update object's XML space.
- */
 void SPObject::attach(SPObject *object, SPObject *prev)
 {
     //g_return_if_fail(parent != NULL);
@@ -625,10 +522,8 @@ void SPObject::attach(SPObject *object, SPObject *prev)
         object->xml_space.value = this->xml_space.value;
 }
 
-/**
- * In list of object's siblings, move object behind prev.
- */
-void SPObject::reorder(SPObject *prev) {
+void SPObject::reorder(SPObject *prev)
+{
     //g_return_if_fail(object != NULL);
     //g_return_if_fail(SP_IS_OBJECT(object));
     g_return_if_fail(this->parent != NULL);
@@ -667,10 +562,8 @@ void SPObject::reorder(SPObject *prev) {
     }
 }
 
-/**
- * Remove object from parent's children, release and unref it.
- */
-void SPObject::detach(SPObject *object) {
+void SPObject::detach(SPObject *object)
+{
     //g_return_if_fail(parent != NULL);
     //g_return_if_fail(SP_IS_OBJECT(parent));
     g_return_if_fail(object != NULL);
@@ -703,9 +596,6 @@ void SPObject::detach(SPObject *object) {
     sp_object_unref(object, this);
 }
 
-/**
- * Return object's child whose node pointer equals repr.
- */
 SPObject *SPObject::get_child_by_repr(Inkscape::XML::Node *repr)
 {
     g_return_val_if_fail(repr != NULL, NULL);
@@ -724,10 +614,6 @@ SPObject *SPObject::get_child_by_repr(Inkscape::XML::Node *repr)
     return result;
 }
 
-/**
- * Callback for child_added event.
- * Invoked whenever the given mutation event happens in the XML tree.
- */
 void SPObject::sp_object_child_added(SPObject *object, Inkscape::XML::Node *child, Inkscape::XML::Node *ref)
 {
     GType type = sp_repr_type_lookup(child);
@@ -742,17 +628,6 @@ void SPObject::sp_object_child_added(SPObject *object, Inkscape::XML::Node *chil
     ochild->invoke_build(object->document, child, object->cloned);
 }
 
-/**
- * Removes, releases and unrefs all children of object.
- *
- * This is the opposite of build. It has to be invoked as soon as the
- * object is removed from the tree, even if it is still alive according
- * to reference count. The frontend unregisters the object from the
- * document and releases the SPRepr bindings; implementations should free
- * state data and release all child objects.  Invoking release on
- * SPRoot destroys the whole document tree.
- * \see sp_object_build()
- */
 void SPObject::sp_object_release(SPObject *object)
 {
     debug("id=%x, typename=%s", object, g_type_name_from_instance((GTypeInstance*)object));
@@ -761,14 +636,6 @@ void SPObject::sp_object_release(SPObject *object)
     }
 }
 
-/**
- * Remove object's child whose node equals repr, release and
- * unref it.
- *
- * Invoked whenever the given mutation event happens in the XML
- * tree, BEFORE removal from the XML tree happens, so grouping
- * objects can safely release the child data.
- */
 void SPObject::sp_object_remove_child(SPObject *object, Inkscape::XML::Node *child)
 {
     debug("id=%x, typename=%s", object, g_type_name_from_instance((GTypeInstance*)object));
@@ -779,12 +646,6 @@ void SPObject::sp_object_remove_child(SPObject *object, Inkscape::XML::Node *chi
     }
 }
 
-/**
- * Move object corresponding to child after sibling object corresponding
- * to new_ref.
- * Invoked whenever the given mutation event happens in the XML tree.
- * \param old_ref Ignored
- */
 void SPObject::sp_object_order_changed(SPObject *object, Inkscape::XML::Node *child, Inkscape::XML::Node */*old_ref*/,
                                     Inkscape::XML::Node *new_ref)
 {
@@ -795,17 +656,6 @@ void SPObject::sp_object_order_changed(SPObject *object, Inkscape::XML::Node *ch
     ochild->_position_changed_signal.emit(ochild);
 }
 
-/**
- * Virtual build callback.
- *
- * This has to be invoked immediately after creation of an SPObject. The
- * frontend method ensures that the new object is properly attached to
- * the document and repr; implementation then will parse all of the attributes,
- * generate the children objects and so on.  Invoking build on the SPRoot
- * object results in creation of the whole document tree (this is, what
- * SPDocument does after the creation of the XML tree).
- * \see sp_object_release()
- */
 void SPObject::sp_object_build(SPObject *object, SPDocument *document, Inkscape::XML::Node *repr)
 {
     /* Nothing specific here */
@@ -967,9 +817,6 @@ SPObject *SPObject::getPrev()
     return prev;
 }
 
-/**
- * Callback for child_added node event.
- */
 void SPObject::sp_object_repr_child_added(Inkscape::XML::Node */*repr*/, Inkscape::XML::Node *child, Inkscape::XML::Node *ref, gpointer data)
 {
     SPObject *object = SP_OBJECT(data);
@@ -979,9 +826,6 @@ void SPObject::sp_object_repr_child_added(Inkscape::XML::Node */*repr*/, Inkscap
     }
 }
 
-/**
- * Callback for remove_child node event.
- */
 void SPObject::sp_object_repr_child_removed(Inkscape::XML::Node */*repr*/, Inkscape::XML::Node *child, Inkscape::XML::Node */*ref*/, gpointer data)
 {
     SPObject *object = SP_OBJECT(data);
@@ -991,11 +835,6 @@ void SPObject::sp_object_repr_child_removed(Inkscape::XML::Node */*repr*/, Inksc
     }
 }
 
-/**
- * Callback for order_changed node event.
- *
- * \todo fixme:
- */
 void SPObject::sp_object_repr_order_changed(Inkscape::XML::Node */*repr*/, Inkscape::XML::Node *child, Inkscape::XML::Node *old, Inkscape::XML::Node *newer, gpointer data)
 {
     SPObject *object = SP_OBJECT(data);
@@ -1005,9 +844,6 @@ void SPObject::sp_object_repr_order_changed(Inkscape::XML::Node */*repr*/, Inksc
     }
 }
 
-/**
- * Callback for set event.
- */
 void SPObject::sp_object_private_set(SPObject *object, unsigned int key, gchar const *value)
 {
     g_assert(key != SP_ATTR_INVALID);
@@ -1093,9 +929,6 @@ void SPObject::sp_object_private_set(SPObject *object, unsigned int key, gchar c
     }
 }
 
-/**
- * Call virtual set() function of object.
- */
 void SPObject::setKeyValue(unsigned int key, gchar const *value)
 {
     //g_assert(object != NULL);
@@ -1106,9 +939,6 @@ void SPObject::setKeyValue(unsigned int key, gchar const *value)
     }
 }
 
-/**
- * Read value of key attribute from XML node into object.
- */
 void SPObject::readAttr(gchar const *key)
 {
     //g_assert(object != NULL);
@@ -1127,9 +957,6 @@ void SPObject::readAttr(gchar const *key)
     }
 }
 
-/**
- * Callback for attr_changed node event.
- */
 void SPObject::sp_object_repr_attr_changed(Inkscape::XML::Node */*repr*/, gchar const *key, gchar const */*oldval*/, gchar const */*newval*/, bool is_interactive, gpointer data)
 {
     SPObject *object = SP_OBJECT(data);
@@ -1143,9 +970,6 @@ void SPObject::sp_object_repr_attr_changed(Inkscape::XML::Node */*repr*/, gchar
     }
 }
 
-/**
- * Callback for content_changed node event.
- */
 void SPObject::sp_object_repr_content_changed(Inkscape::XML::Node */*repr*/, gchar const */*oldcontent*/, gchar const */*newcontent*/, gpointer data)
 {
     SPObject *object = SP_OBJECT(data);
@@ -1158,8 +982,7 @@ void SPObject::sp_object_repr_content_changed(Inkscape::XML::Node */*repr*/, gch
 /**
  * Return string representation of space value.
  */
-static gchar const*
-sp_xml_get_space_string(unsigned int space)
+static gchar const *sp_xml_get_space_string(unsigned int space)
 {
     switch (space) {
         case SP_XML_SPACE_DEFAULT:
@@ -1171,9 +994,6 @@ sp_xml_get_space_string(unsigned int space)
     }
 }
 
-/**
- * Callback for write event.
- */
 Inkscape::XML::Node * SPObject::sp_object_private_write(SPObject *object, Inkscape::XML::Document *doc, Inkscape::XML::Node *repr, guint flags)
 {
     if (!repr && (flags & SP_OBJECT_WRITE_BUILD)) {
@@ -1234,10 +1054,8 @@ Inkscape::XML::Node * SPObject::sp_object_private_write(SPObject *object, Inksca
     return repr;
 }
 
-/**
- * Update this object's XML node with flags value.
- */
-Inkscape::XML::Node * SPObject::updateRepr(unsigned int flags) {
+Inkscape::XML::Node * SPObject::updateRepr(unsigned int flags)
+{
     if ( !cloned ) {
         Inkscape::XML::Node *repr = getRepr();
         if (repr) {
@@ -1252,11 +1070,8 @@ Inkscape::XML::Node * SPObject::updateRepr(unsigned int flags) {
     }
 }
 
-/** Used both to create reprs in the original document, and to create
- *  reprs in another document (e.g. a temporary document used when
- *  saving as "Plain SVG"
- */
-Inkscape::XML::Node * SPObject::updateRepr(Inkscape::XML::Document *doc, Inkscape::XML::Node *repr, unsigned int flags) {
+Inkscape::XML::Node * SPObject::updateRepr(Inkscape::XML::Document *doc, Inkscape::XML::Node *repr, unsigned int flags)
+{
     g_assert(doc != NULL);
 
     if (cloned) {
@@ -1284,11 +1099,6 @@ Inkscape::XML::Node * SPObject::updateRepr(Inkscape::XML::Document *doc, Inkscap
 
 /* Modification */
 
-/**
- * Add \a flags to \a object's as dirtiness flags, and
- * recursively add CHILD_MODIFIED flag to
- * parent and ancestors (as far up as necessary).
- */
 void SPObject::requestDisplayUpdate(unsigned int flags)
 {
     g_return_if_fail( this->document != NULL );
@@ -1319,9 +1129,6 @@ void SPObject::requestDisplayUpdate(unsigned int flags)
     }
 }
 
-/**
- * Update views
- */
 void SPObject::updateDisplay(SPCtx *ctx, unsigned int flags)
 {
     g_return_if_fail(!(flags & ~SP_OBJECT_MODIFIED_CASCADE));
@@ -1370,11 +1177,6 @@ void SPObject::updateDisplay(SPCtx *ctx, unsigned int flags)
     update_in_progress --;
 }
 
-/**
- * Request modified always bubbles *up* the tree, as opposed to
- * request display update, which trickles down and relies on the
- * flags set during this pass...
- */
 void SPObject::requestModified(unsigned int flags)
 {
     g_return_if_fail( this->document != NULL );
@@ -1401,12 +1203,6 @@ void SPObject::requestModified(unsigned int flags)
     }
 }
 
-/**
- *  Emits the MODIFIED signal with the object's flags.
- *  The object's mflags are the original set aside during the update pass for
- *  later delivery here.  Once emitModified() is called, those flags don't
- *  need to be stored any longer.
- */
 void SPObject::emitModified(unsigned int flags)
 {
     /* only the MODIFIED_CASCADE flag is legal here */
@@ -1522,36 +1318,8 @@ gchar * SPObject::sp_object_get_unique_id(SPObject *object, gchar const *id)
     return buf;
 }
 
-/* Style */
+// Style
 
-/**
- * Returns an object style property.
- *
- * \todo
- * fixme: Use proper CSS parsing.  The current version is buggy
- * in a number of situations where key is a substring of the
- * style string other than as a property name (including
- * where key is a substring of a property name), and is also
- * buggy in its handling of inheritance for properties that
- * aren't inherited by default.  It also doesn't allow for
- * the case where the property is specified but with an invalid
- * value (in which case I believe the CSS2 error-handling
- * behaviour applies, viz. behave as if the property hadn't
- * been specified).  Also, the current code doesn't use CRSelEng
- * stuff to take a value from stylesheets.  Also, we aren't
- * setting any hooks to force an update for changes in any of
- * the inputs (i.e., in any of the elements that this function
- * queries).
- *
- * \par
- * Given that the default value for a property depends on what
- * property it is (e.g., whether to inherit or not), and given
- * the above comment about ignoring invalid values, and that the
- * repr parent isn't necessarily the right element to inherit
- * from (e.g., maybe we need to inherit from the referencing
- * <use> element instead), we should probably make the caller
- * responsible for ascending the repr tree as necessary.
- */
 gchar const * SPObject::getStyleProperty(gchar const *key, gchar const *def) const
 {
     //g_return_val_if_fail(object != NULL, NULL);
@@ -1599,9 +1367,6 @@ gchar const * SPObject::getStyleProperty(gchar const *key, gchar const *def) con
     return def;
 }
 
-/**
- * Lifts SVG version of all root objects to version.
- */
 void SPObject::_requireSVGVersion(Inkscape::Version version) {
     for ( SPObject::ParentIterator iter=this ; iter ; ++iter ) {
         SPObject *object = iter;
@@ -1614,7 +1379,7 @@ void SPObject::_requireSVGVersion(Inkscape::Version version) {
     }
 }
 
-/* Titles and descriptions */
+// Titles and descriptions
 
 /* Note:
    Titles and descriptions are stored in 'title' and 'desc' child elements
@@ -1626,58 +1391,26 @@ void SPObject::_requireSVGVersion(Inkscape::Version version) {
    element, except when deleting a title or description.
 */
 
-/**
- * Returns the title of this object, or NULL if there is none.
- * The caller must free the returned string using g_free() - see comment
- * for getTitleOrDesc() below.
- */
 gchar * SPObject::title() const
 {
     return getTitleOrDesc("svg:title");
 }
 
-/**
- * Sets the title of this object
- * A NULL first argument is interpreted as meaning that the existing title
- * (if any) should be deleted.
- * The second argument is optional - see setTitleOrDesc() below for details.
- */
 bool SPObject::setTitle(gchar const *title, bool verbatim)
 {
     return setTitleOrDesc(title, "svg:title", verbatim);
 }
 
-/**
- * Returns the description of this object, or NULL if there is none.
- * The caller must free the returned string using g_free() - see comment
- * for getTitleOrDesc() below.
- */
 gchar * SPObject::desc() const
 {
     return getTitleOrDesc("svg:desc");
 }
 
-/**
- * Sets the description of this object.
- * A NULL first argument is interpreted as meaning that the existing
- * description (if any) should be deleted.
- * The second argument is optional - see setTitleOrDesc() below for details.
- */
 bool SPObject::setDesc(gchar const *desc, bool verbatim)
 {
     return setTitleOrDesc(desc, "svg:desc", verbatim);
 }
 
-/**
- * Returns the title or description of this object, or NULL if there is none.
- *
- * The SVG spec allows 'title' and 'desc' elements to contain text marked up
- * using elements from other namespaces.  Therefore, this function cannot
- * in general just return a pointer to an existing string - it must instead
- * construct a string containing the title or description without the mark-up.
- * Consequently, the return value is a newly allocated string (or NULL), and
- * must be freed (using g_free()) by the caller.
- */
 gchar * SPObject::getTitleOrDesc(gchar const *svg_tagname) const
 {
     gchar *result = 0;
@@ -1688,23 +1421,6 @@ gchar * SPObject::getTitleOrDesc(gchar const *svg_tagname) const
     return result;
 }
 
-/**
- * Sets or deletes the title or description of this object.
- * A NULL 'value' argument causes the title or description to be deleted.
- *
- * 'verbatim' parameter:
- * If verbatim==true, then the title or description is set to exactly the
- * specified value.  If verbatim==false then two exceptions are made:
- *   (1) If the specified value is just whitespace, then the title/description
- *       is deleted.
- *   (2) If the specified value is the same as the current value except for
- *       mark-up, then the current value is left unchanged.
- * This is usually the desired behaviour, so 'verbatim' defaults to false for
- * setTitle() and setDesc().
- *
- * The return value is true if a change was made to the title/description,
- * and usually false otherwise.
- */
 bool SPObject::setTitleOrDesc(gchar const *value, gchar const *svg_tagname, bool verbatim)
 {
     if (!verbatim) {
@@ -1770,10 +1486,6 @@ bool SPObject::setTitleOrDesc(gchar const *value, gchar const *svg_tagname, bool
     return true;
 }
 
-/**
- * Find the first child of this object with a given tag name,
- * and return it.  Returns NULL if there is no matching child.
- */
 SPObject * SPObject::findFirstChild(gchar const *tagname) const
 {
     for (SPObject *child = children; child; child = child->next)
@@ -1786,11 +1498,6 @@ SPObject * SPObject::findFirstChild(gchar const *tagname) const
     return NULL;
 }
 
-/**
- * Return the full textual content of an element (typically all the
- * content except the tags).
- * Must not be used on anything except elements.
- */
 GString * SPObject::textualContent() const
 {
     GString* text = g_string_new("");
diff --git a/src/sp-object.h b/src/sp-object.h
index 3999dc622..49e36d773 100644
--- a/src/sp-object.h
+++ b/src/sp-object.h
@@ -126,16 +126,71 @@ struct SPIXmlSpace {
  * Ref should return object, NULL is error, unref return always NULL
  */
 
+/**
+ * Increase reference count of object, with possible debugging.
+ *
+ * @param owner If non-NULL, make debug log entry.
+ * @return object, NULL is error.
+ * \pre object points to real object
+ * @todo need to move this to be a member of SPObject.
+ */
 SPObject *sp_object_ref(SPObject *object, SPObject *owner=NULL);
+
+/**
+ * Decrease reference count of object, with possible debugging and
+ * finalization.
+ *
+ * @param owner If non-NULL, make debug log entry.
+ * @return always NULL
+ * \pre object points to real object
+ * @todo need to move this to be a member of SPObject.
+ */
 SPObject *sp_object_unref(SPObject *object, SPObject *owner=NULL);
 
+/**
+ * Increase weak refcount.
+ *
+ * Hrefcount is used for weak references, for example, to
+ * determine whether any graphical element references a certain gradient
+ * node.
+ * @param owner Ignored.
+ * @return object, NULL is error
+ * \pre object points to real object
+ * @todo need to move this to be a member of SPObject.
+ */
 SPObject *sp_object_href(SPObject *object, gpointer owner);
+
+/**
+ * Decrease weak refcount.
+ *
+ * Hrefcount is used for weak references, for example, to determine whether
+ * any graphical element references a certain gradient node.
+ * @param owner Ignored.
+ * @return always NULL
+ * \pre object points to real object and hrefcount>0
+ * @todo need to move this to be a member of SPObject.
+ */
 SPObject *sp_object_hunref(SPObject *object, gpointer owner);
 
 
 /**
- * Abstract base class for all nodes.
- * A refcounting tree node object.
+ * SPObject is an abstract base class of all of the document nodes at the
+ * SVG document level. Each SPObject subclass implements a certain SVG
+ * element node type, or is an abstract base class for different node
+ * types.  The SPObject layer is bound to the SPRepr layer, closely
+ * following the SPRepr mutations via callbacks.  During creation,
+ * SPObject parses and interprets all textual attributes and CSS style
+ * strings of the SPRepr, and later updates the internal state whenever
+ * it receives a signal about a change. The opposite is not true - there
+ * are methods manipulating SPObjects directly and such changes do not
+ * propagate to the SPRepr layer. This is important for implementation of
+ * the undo stack, animations and other features.
+ *
+ * SPObjects are bound to the higher-level container SPDocument, which
+ * provides document level functionality such as the undo stack,
+ * dictionary and so on. Source: doc/architecture.txt
+ *
+ * @todo need to remove redundant sp_object_... prefixing on methods.
  */
 class SPObject : public GObject {
 public:
@@ -180,16 +235,18 @@ public:
 
 public:
 
-    /** @brief cleans up an SPObject, releasing its references and
-     *         requesting that references to it be released
+    /**
+     * Cleans up an SPObject, releasing its references and
+     * requesting that references to it be released
      */
     void releaseReferences();
 
-    /** @brief connects to the release request signal
+    /**
+     * Connects to the release request signal
      *
-     *  @param slot the slot to connect
+     * @param slot the slot to connect
      *
-     *  @returns the sigc::connection formed
+     * @return the sigc::connection formed
      */
     sigc::connection connectRelease(sigc::slot<void, SPObject *> slot) {
         return _release_signal.connect(slot);
@@ -230,13 +287,21 @@ public:
         g_return_val_if_fail(object != NULL, false);
         return this->parent && this->parent == object->parent;
     }
+
+    /**
+     * True if object is non-NULL and this is some in/direct parent of object.
+     */
     bool isAncestorOf(SPObject const *object) const;
 
+    /**
+     * Returns youngest object being parent to this and object.
+     */
     SPObject const *nearestCommonAncestor(SPObject const *object) const;
+
     /* A non-const version can be similarly constructed if you want one.
      * (Don't just cast away the constness, which would be ill-formed.) */
-
     SPObject *getNext() {return next;}
+
     SPObject const *getNext() const {return next;}
 
     /**
@@ -260,32 +325,62 @@ public:
      */
     GSList *childList(bool add_ref, Action action = ActionGeneral);
 
+    /**
+     * Append repr as child of this object.
+     * \pre this is not a cloned object
+     */
     SPObject *appendChildRepr(Inkscape::XML::Node *repr);
 
-    /** @brief Gets the author-visible label for this object. */
+    /**
+     * Gets the author-visible label property for the object or a default if
+     * no label is defined.
+     */
     gchar const *label() const;
-    /** @brief Returns a default label for this object. */
+
+    /**
+     * Returns a default label property for this object.
+     */
     gchar const *defaultLabel() const;
-    /** @brief Sets the author-visible label for this object.
-     *
-     * Sets the author-visible label for the object.
+
+    /**
+     * Sets the author-visible label for this object.
      *
-     * @param label the new label
+     * @param label the new label.
      */
     void setLabel(gchar const *label);
 
-    /** Retrieves the title of this object */
+    /**
+     * Returns the title of this object, or NULL if there is none.
+     * The caller must free the returned string using g_free() - see comment
+     * for getTitleOrDesc() below.
+     */
     gchar *title() const;
-    /** Sets the title of this object */
-    bool setTitle(gchar const *title, bool verbatim=false);
 
-    /** Retrieves the description of this object */
+    /**
+     * Sets the title of this object.
+     * A NULL first argument is interpreted as meaning that the existing title
+     * (if any) should be deleted.
+     * The second argument is optional - @see setTitleOrDesc() below for details.
+     */
+    bool setTitle(gchar const *title, bool verbatim = false);
+
+    /**
+     * Returns the description of this object, or NULL if there is none.
+     * The caller must free the returned string using g_free() - see comment
+     * for getTitleOrDesc() below.
+     */
     gchar *desc() const;
-    /** Sets the description of this object */
+
+    /**
+     * Sets the description of this object.
+     * A NULL first argument is interpreted as meaning that the existing
+     * description (if any) should be deleted.
+     * The second argument is optional - @see setTitleOrDesc() below for details.
+     */
     bool setDesc(gchar const *desc, bool verbatim=false);
 
-    /** @brief Set the policy under which this object will be
-     *         orphan-collected.
+    /**
+     * Set the policy under which this object will be orphan-collected.
      *
      * Orphan-collection is the process of deleting all objects which no longer have
      * hyper-references pointing to them.  The policy determines when this happens.  Many objects
@@ -302,21 +397,23 @@ public:
      *  COLLECT_ALWAYS - always collect the object as soon as its
      *                   hrefcount reaches zero
      *
-     * @returns the current collection policy in effect for this object
+     * @return the current collection policy in effect for this object
      */
     CollectionPolicy collectionPolicy() const { return _collection_policy; }
 
-    /** @brief Sets the orphan-collection policy in effect for this object.
-     *
-     * @see SPObject::collectionPolicy
+    /**
+     * Sets the orphan-collection policy in effect for this object.
      *
      * @param policy the new policy to adopt
+     *
+     * @see SPObject::collectionPolicy
      */
     void setCollectionPolicy(CollectionPolicy policy) {
         _collection_policy = policy;
     }
 
-    /** @brief Requests a later automatic call to collectOrphan().
+    /**
+     * Requests a later automatic call to collectOrphan().
      *
      * This method requests that collectOrphan() be called during the document update cycle,
      * deleting the object if it is no longer used.
@@ -327,7 +424,8 @@ public:
      */
     void requestOrphanCollection();
 
-    /** @brief Unconditionally delete the object if it is not referenced.
+    /**
+     * Unconditionally delete the object if it is not referenced.
      *
      * Unconditionally delete the object if there are no outstanding hyper-references to it.
      * Observers are not notified of the object's deletion (at the SPObject level; XML tree
@@ -341,31 +439,36 @@ public:
         }
     }
 
-    /** @brief Check if object is referenced by any other object.
+    /**
+     * Check if object is referenced by any other object.
      */
     bool isReferenced() { return ( _total_hrefcount > 0 ); }
 
-    /** @brief Deletes an object.
+    /**
+     * Deletes an object, unparenting it from its parent.
      *
      * Detaches the object's repr, and optionally sends notification that the object has been
      * deleted.
      *
-     * @param propagate notify observers that the object has been deleted?
+     * @param propagate If it is set to true, it emits a delete signal.
      *
-     * @param propagate_descendants notify observers of children that they have been deleted?
+     * @param propagate_descendants If it is is true, it recursively sends the delete signal to children.
      */
     void deleteObject(bool propagate, bool propagate_descendants);
 
-    /** @brief Deletes on object.
+    /**
+     * Deletes on object.
      *
      * @param propagate Notify observers of this object and its children that they have been
      *                  deleted?
      */
-    void deleteObject(bool propagate=true) {
+    void deleteObject(bool propagate = true)
+    {
         deleteObject(propagate, propagate);
     }
 
-    /** @brief Connects a slot to be called when an object is deleted.
+    /**
+     * Connects a slot to be called when an object is deleted.
      *
      * This connects a slot to an object's internal delete signal, which is invoked when the object
      * is deleted
@@ -384,14 +487,17 @@ public:
         return _position_changed_signal.connect(slot);
     }
 
-    /** @brief Returns the object which supercedes this one (if any).
+    /**
+     * Returns the object which supercedes this one (if any).
      *
      * This is mainly useful for ensuring we can correctly perform a series of moves or deletes,
      * even if the objects in question have been replaced in the middle of the sequence.
      */
     SPObject *successor() { return _successor; }
 
-    /** @brief Indicates that another object supercedes this one. */
+    /**
+     * Indicates that another object supercedes this one.
+     */
     void setSuccessor(SPObject *successor) {
         g_assert(successor != NULL);
         g_assert(_successor == NULL);
@@ -408,18 +514,23 @@ public:
      * essentially just flushes any changes back to the backing store (the repr layer); maybe it
      * should be called something else and made public at that point. */
 
-    /** @brief Updates the object's repr based on the object's state.
+    /**
+     * Updates the object's repr based on the object's state.
      *
      *  This method updates the the repr attached to the object to reflect the object's current
      *  state; see the three-argument version for details.
      *
-     *  @param flags object write flags that apply to this update
+     * @param flags object write flags that apply to this update
      *
-     *  @return the updated repr
+     * @return the updated repr
      */
-    Inkscape::XML::Node *updateRepr(unsigned int flags=SP_OBJECT_WRITE_EXT);
+    Inkscape::XML::Node *updateRepr(unsigned int flags = SP_OBJECT_WRITE_EXT);
 
-    /** @brief Updates the given repr based on the object's state.
+    /**
+     * Updates the given repr based on the object's state.
+     *
+     * Used both to create reprs in the original document, and to create reprs
+     * in another document (e.g. a temporary document used when saving as "Plain SVG".
      *
      *  This method updates the given repr to reflect the object's current state.  There are
      *  several flags that affect this:
@@ -434,14 +545,15 @@ public:
      *   SP_OBJECT_WRITE_ALL   - create all nodes and attributes,
      *                           even those which might be redundant
      *
-     *  @param repr the repr to update
-     *  @param flags object write flags that apply to this update
+     * @param repr the repr to update
+     * @param flags object write flags that apply to this update
      *
-     *  @return the updated repr
+     * @return the updated repr
      */
     Inkscape::XML::Node *updateRepr(Inkscape::XML::Document *doc, Inkscape::XML::Node *repr, unsigned int flags);
 
-    /** @brief Queues an deferred update of this object's display.
+    /**
+     * Queues an deferred update of this object's display.
      *
      *  This method sets flags to indicate updates to be performed later, during the idle loop.
      *
@@ -459,11 +571,12 @@ public:
      *
      *  One of either MODIFIED or CHILD_MODIFIED is required.
      *
-     *  @param flags flags indicating what to update
+     * @param flags flags indicating what to update
      */
     void requestDisplayUpdate(unsigned int flags);
 
-    /** @brief Updates the object's display immediately
+    /**
+     * Updates the object's display immediately
      *
      *  This method is called during the idle loop by SPDocument in order to update the object's
      *  display.
@@ -473,33 +586,43 @@ public:
      *   SP_OBJECT_PARENT_MODIFIED_FLAG - the parent has been
      *                                    modified
      *
-     *  @param ctx an SPCtx which accumulates various state
+     * @param ctx an SPCtx which accumulates various state
      *             during the recursive update -- beware! some
      *             subclasses try to cast this to an SPItemCtx *
      *
-     *  @param flags flags indicating what to update (in addition
+     * @param flags flags indicating what to update (in addition
      *               to any already set flags)
      */
     void updateDisplay(SPCtx *ctx, unsigned int flags);
 
-    /** @brief Requests that a modification notification signal
-     *         be emitted later (e.g. during the idle loop)
+    /**
+     * Requests that a modification notification signal
+     * be emitted later (e.g. during the idle loop)
+     *
+     * Request modified always bubbles *up* the tree, as opposed to
+     * request display update, which trickles down and relies on the
+     * flags set during this pass...
      *
-     *  @param flags flags indicating what has been modified
+     * @param flags flags indicating what has been modified
      */
     void requestModified(unsigned int flags);
 
-    /** @brief Emits a modification notification signal
+    /**
+     *  Emits the MODIFIED signal with the object's flags.
+     *  The object's mflags are the original set aside during the update pass for
+     *  later delivery here.  Once emitModified() is called, those flags don't
+     *  need to be stored any longer.
      *
-     *  @param flags indicating what has been modified
+     * @param flags indicating what has been modified.
      */
     void emitModified(unsigned int flags);
 
-    /** @brief Connects to the modification notification signal
+    /**
+     * Connects to the modification notification signal
      *
-     *  @param slot the slot to connect
+     * @param slot the slot to connect
      *
-     *  @returns the connection formed thereby
+     * @return the connection formed thereby
      */
     sigc::connection connectModified(
       sigc::slot<void, SPObject *, unsigned int> slot
@@ -510,11 +633,18 @@ public:
     /** Sends the delete signal to all children of this object recursively */
     void _sendDeleteSignalRecursive();
 
+    /**
+     * Adds increment to _total_hrefcount of object and its parents.
+     */
     void _updateTotalHRefCount(int increment);
 
     void _requireSVGVersion(unsigned major, unsigned minor) {
         _requireSVGVersion(Inkscape::Version(major, minor));
     }
+
+    /**
+     * Lifts SVG version of all root objects to version.
+     */
     void _requireSVGVersion(Inkscape::Version version);
 
     sigc::signal<void, SPObject *> _release_signal;
@@ -530,59 +660,246 @@ public:
     // Methods below should not be used outside of the SP tree,
     // as they operate directly on the XML representation.
     // In future, they will be made protected.
+
+    /**
+     * Put object into object tree, under parent, and behind prev;
+     * also update object's XML space.
+     */
     void attach(SPObject *object, SPObject *prev);
+
+    /**
+     * In list of object's siblings, move object behind prev.
+     */
     void reorder(SPObject *prev);
+
+    /**
+     * Remove object from parent's children, release and unref it.
+     */
     void detach(SPObject *object);
+
+    /**
+     * Return object's child whose node pointer equals repr.
+     */
     SPObject *get_child_by_repr(Inkscape::XML::Node *repr);
+
     void invoke_build(SPDocument *document, Inkscape::XML::Node *repr, unsigned int cloned);
+
     long long int getIntAttribute(char const *key, long long int def);
+
     unsigned getPosition();
+
     gchar const * getAttribute(gchar const *name,SPException *ex=0) const;
+
     void appendChild(Inkscape::XML::Node *child);
+
     void addChild(Inkscape::XML::Node *child,Inkscape::XML::Node *prev=0);
+
+    /**
+     * Call virtual set() function of object.
+     */
     void setKeyValue(unsigned int key, gchar const *value);
+
     void setAttribute(gchar const *key, gchar const *value, SPException *ex=0);
+
+    /**
+     * Read value of key attribute from XML node into object.
+     */
     void readAttr(gchar const *key);
+
     gchar const *getTagName(SPException *ex) const;
+
     void removeAttribute(gchar const *key, SPException *ex=0);
+
+    /**
+     * Returns an object style property.
+     *
+     * \todo
+     * fixme: Use proper CSS parsing.  The current version is buggy
+     * in a number of situations where key is a substring of the
+     * style string other than as a property name (including
+     * where key is a substring of a property name), and is also
+     * buggy in its handling of inheritance for properties that
+     * aren't inherited by default.  It also doesn't allow for
+     * the case where the property is specified but with an invalid
+     * value (in which case I believe the CSS2 error-handling
+     * behaviour applies, viz. behave as if the property hadn't
+     * been specified).  Also, the current code doesn't use CRSelEng
+     * stuff to take a value from stylesheets.  Also, we aren't
+     * setting any hooks to force an update for changes in any of
+     * the inputs (i.e., in any of the elements that this function
+     * queries).
+     *
+     * \par
+     * Given that the default value for a property depends on what
+     * property it is (e.g., whether to inherit or not), and given
+     * the above comment about ignoring invalid values, and that the
+     * repr parent isn't necessarily the right element to inherit
+     * from (e.g., maybe we need to inherit from the referencing
+     * <use> element instead), we should probably make the caller
+     * responsible for ascending the repr tree as necessary.
+     */
     gchar const *getStyleProperty(gchar const *key, gchar const *def) const;
+
     void setCSS(SPCSSAttr *css, gchar const *attr);
+
     void changeCSS(SPCSSAttr *css, gchar const *attr);
+
     bool storeAsDouble( gchar const *key, double *val ) const;
 
 private:
     // Private member functions used in the definitions of setTitle(),
     // setDesc(), title() and desc().
+
+    /**
+     * Sets or deletes the title or description of this object.
+     * A NULL 'value' argument causes the title or description to be deleted.
+     *
+     * 'verbatim' parameter:
+     * If verbatim==true, then the title or description is set to exactly the
+     * specified value.  If verbatim==false then two exceptions are made:
+     *   (1) If the specified value is just whitespace, then the title/description
+     *       is deleted.
+     *   (2) If the specified value is the same as the current value except for
+     *       mark-up, then the current value is left unchanged.
+     * This is usually the desired behaviour, so 'verbatim' defaults to false for
+     * setTitle() and setDesc().
+     *
+     * The return value is true if a change was made to the title/description,
+     * and usually false otherwise.
+     */
     bool setTitleOrDesc(gchar const *value, gchar const *svg_tagname, bool verbatim);
+
+    /**
+     * Returns the title or description of this object, or NULL if there is none.
+     *
+     * The SVG spec allows 'title' and 'desc' elements to contain text marked up
+     * using elements from other namespaces.  Therefore, this function cannot
+     * in general just return a pointer to an existing string - it must instead
+     * construct a string containing the title or description without the mark-up.
+     * Consequently, the return value is a newly allocated string (or NULL), and
+     * must be freed (using g_free()) by the caller.
+     */
     gchar * getTitleOrDesc(gchar const *svg_tagname) const;
+
+    /**
+     * Find the first child of this object with a given tag name,
+     * and return it.  Returns NULL if there is no matching child.
+     */
     SPObject * findFirstChild(gchar const *tagname) const;
+
+    /**
+     * Return the full textual content of an element (typically all the
+     * content except the tags).
+     * Must not be used on anything except elements.
+     */
     GString * textualContent() const;
 
+    /**
+     * Callback to initialize the SPObject object.
+     */
     static void sp_object_init(SPObject *object);
+
+    /**
+     * Callback to destroy all members and connections of object and itself.
+     */
     static void sp_object_finalize(GObject *object);
 
+    /**
+     * Callback for child_added event.
+     * Invoked whenever the given mutation event happens in the XML tree.
+     */
     static void sp_object_child_added(SPObject *object, Inkscape::XML::Node *child, Inkscape::XML::Node *ref);
+
+    /**
+     * Remove object's child whose node equals repr, release and
+     * unref it.
+     *
+     * Invoked whenever the given mutation event happens in the XML
+     * tree, BEFORE removal from the XML tree happens, so grouping
+     * objects can safely release the child data.
+     */
     static void sp_object_remove_child(SPObject *object, Inkscape::XML::Node *child);
+
+    /**
+     * Move object corresponding to child after sibling object corresponding
+     * to new_ref.
+     * Invoked whenever the given mutation event happens in the XML tree.
+     * @param old_ref Ignored
+     */
     static void sp_object_order_changed(SPObject *object, Inkscape::XML::Node *child, Inkscape::XML::Node *old_ref, Inkscape::XML::Node *new_ref);
 
+    /**
+     * Removes, releases and unrefs all children of object.
+     *
+     * This is the opposite of build. It has to be invoked as soon as the
+     * object is removed from the tree, even if it is still alive according
+     * to reference count. The frontend unregisters the object from the
+     * document and releases the SPRepr bindings; implementations should free
+     * state data and release all child objects.  Invoking release on
+     * SPRoot destroys the whole document tree.
+     * @see sp_object_build()
+     */
     static void sp_object_release(SPObject *object);
+
+    /**
+     * Virtual build callback.
+     *
+     * This has to be invoked immediately after creation of an SPObject. The
+     * frontend method ensures that the new object is properly attached to
+     * the document and repr; implementation then will parse all of the attributes,
+     * generate the children objects and so on.  Invoking build on the SPRoot
+     * object results in creation of the whole document tree (this is, what
+     * SPDocument does after the creation of the XML tree).
+     * @see sp_object_release()
+     */
     static void sp_object_build(SPObject *object, SPDocument *document, Inkscape::XML::Node *repr);
 
+    /**
+     * Callback for set event.
+     */
     static void sp_object_private_set(SPObject *object, unsigned int key, gchar const *value);
+
+    /**
+     * Callback for write event.
+     */
     static Inkscape::XML::Node *sp_object_private_write(SPObject *object, Inkscape::XML::Document *doc, Inkscape::XML::Node *repr, guint flags);
+
     static gchar *sp_object_get_unique_id(SPObject *object, gchar const *defid);
 
     /* Real handlers of repr signals */
 
 public:
+
+    /**
+     * Registers the SPObject class with Gdk and returns its type number.
+     */
     static GType sp_object_get_type();
+
+    /**
+     * Callback for attr_changed node event.
+     */
     static void sp_object_repr_attr_changed(Inkscape::XML::Node *repr, gchar const *key, gchar const *oldval, gchar const *newval, bool is_interactive, gpointer data);
 
+    /**
+     * Callback for content_changed node event.
+     */
     static void sp_object_repr_content_changed(Inkscape::XML::Node *repr, gchar const *oldcontent, gchar const *newcontent, gpointer data);
 
+    /**
+     * Callback for child_added node event.
+     */
     static void sp_object_repr_child_added(Inkscape::XML::Node *repr, Inkscape::XML::Node *child, Inkscape::XML::Node *ref, gpointer data);
+
+    /**
+     * Callback for remove_child node event.
+     */
     static void sp_object_repr_child_removed(Inkscape::XML::Node *repr, Inkscape::XML::Node *child, Inkscape::XML::Node *ref, void *data);
 
+    /**
+     * Callback for order_changed node event.
+     *
+     * \todo fixme:
+     */
     static void sp_object_repr_order_changed(Inkscape::XML::Node *repr, Inkscape::XML::Node *child, Inkscape::XML::Node *old, Inkscape::XML::Node *newer, gpointer data);
 
 
@@ -617,12 +934,25 @@ public:
 
 private:
     static GObjectClass *static_parent_class;
+
+    /**
+     * Initializes the SPObject vtable.
+     */
     static void sp_object_class_init(SPObjectClass *klass);
 
     friend class SPObject;
 };
 
 
+/**
+ * Compares height of objects in tree.
+ *
+ * Works for different-parent objects, so long as they have a common ancestor.
+ * \return \verbatim
+ *    0    positions are equivalent
+ *    1    first object's position is greater than the second
+ *   -1    first object's position is less than the second   \endverbatim
+ */
 int sp_object_compare_position(SPObject const *first, SPObject const *second);
 
 
diff --git a/src/svg-view-widget.cpp b/src/svg-view-widget.cpp
index cda1ed546..44a2d4b2d 100644
--- a/src/svg-view-widget.cpp
+++ b/src/svg-view-widget.cpp
@@ -1,5 +1,5 @@
-/** \file
- * Functions and callbacks for generic SVG view and widget
+/*
+ * Functions and callbacks for generic SVG view and widget.
  *
  * Authors:
  *   Lauris Kaplinski <lauris@kaplinski.com>
@@ -33,9 +33,6 @@ static void sp_svg_view_widget_view_resized (SPViewWidget *vw, Inkscape::UI::Vie
 
 static SPViewWidgetClass *widget_parent_class;
 
-/**
- * Registers SPSVGSPViewWidget class with Gtk and returns its type number.
- */
 GType sp_svg_view_widget_get_type(void)
 {
     static GType type = 0;
@@ -60,8 +57,7 @@ GType sp_svg_view_widget_get_type(void)
 /**
  * Callback to initialize SPSVGSPViewWidget vtable.
  */
-static void
-sp_svg_view_widget_class_init (SPSVGSPViewWidgetClass *klass)
+static void sp_svg_view_widget_class_init(SPSVGSPViewWidgetClass *klass)
 {
 	GtkObjectClass *object_class = GTK_OBJECT_CLASS (klass);
 	GtkWidgetClass *widget_class = GTK_WIDGET_CLASS (klass);
@@ -80,8 +76,7 @@ sp_svg_view_widget_class_init (SPSVGSPViewWidgetClass *klass)
 /**
  * Callback to initialize SPSVGSPViewWidget object.
  */
-static void
-sp_svg_view_widget_init (SPSVGSPViewWidget *vw)
+static void sp_svg_view_widget_init(SPSVGSPViewWidget *vw)
 {
 	GtkStyle *style;
 	SPCanvasItem *parent;
@@ -124,21 +119,22 @@ sp_svg_view_widget_destroy (GtkObject *object)
 
 	vw->canvas = NULL;
 
-	if (((GtkObjectClass *) (widget_parent_class))->destroy)
+	if (((GtkObjectClass *) (widget_parent_class))->destroy) {
 		(* ((GtkObjectClass *) (widget_parent_class))->destroy) (object);
+        }
 }
 
 /**
  * Callback connected with size_request signal.
  */
-static void
-sp_svg_view_widget_size_request (GtkWidget *widget, GtkRequisition *req)
+static void sp_svg_view_widget_size_request(GtkWidget *widget, GtkRequisition *req)
 {
 	SPSVGSPViewWidget *vw = SP_SVG_VIEW_WIDGET (widget);
 	Inkscape::UI::View::View *v = SP_VIEW_WIDGET_VIEW (widget);
 
-	if (((GtkWidgetClass *) (widget_parent_class))->size_request)
+	if (((GtkWidgetClass *) (widget_parent_class))->size_request) {
 		(* ((GtkWidgetClass *) (widget_parent_class))->size_request) (widget, req);
+        }
 
 	if (v->doc()) {
 		SPSVGView *svgv;
@@ -170,13 +166,13 @@ sp_svg_view_widget_size_request (GtkWidget *widget, GtkRequisition *req)
 /**
  * Callback connected with size_allocate signal.
  */
-static void
-sp_svg_view_widget_size_allocate (GtkWidget *widget, GtkAllocation *allocation)
+static void sp_svg_view_widget_size_allocate(GtkWidget *widget, GtkAllocation *allocation)
 {
 	SPSVGSPViewWidget *svgvw = SP_SVG_VIEW_WIDGET (widget);
 
-	if (((GtkWidgetClass *) (widget_parent_class))->size_allocate)
+	if (((GtkWidgetClass *) (widget_parent_class))->size_allocate) {
 		(* ((GtkWidgetClass *) (widget_parent_class))->size_allocate) (widget, allocation);
+        }
 
 	if (!svgvw->resize) {
 		static_cast<SPSVGView*>(SP_VIEW_WIDGET_VIEW (svgvw))->setRescale (TRUE, TRUE,
@@ -187,8 +183,7 @@ sp_svg_view_widget_size_allocate (GtkWidget *widget, GtkAllocation *allocation)
 /**
  * Callback connected with view_resized signal.
  */
-static void
-sp_svg_view_widget_view_resized (SPViewWidget *vw, Inkscape::UI::View::View */*view*/, gdouble width, gdouble height)
+static void sp_svg_view_widget_view_resized(SPViewWidget *vw, Inkscape::UI::View::View */*view*/, gdouble width, gdouble height)
 {
 	SPSVGSPViewWidget *svgvw = SP_SVG_VIEW_WIDGET (vw);
 
@@ -198,11 +193,7 @@ sp_svg_view_widget_view_resized (SPViewWidget *vw, Inkscape::UI::View::View */*v
 	}
 }
 
-/**
- * Constructs new SPSVGSPViewWidget object and returns pointer to it.
- */
-GtkWidget *
-sp_svg_view_widget_new (SPDocument *doc)
+GtkWidget *sp_svg_view_widget_new(SPDocument *doc)
 {
 	GtkWidget *widget;
 
@@ -215,9 +206,6 @@ sp_svg_view_widget_new (SPDocument *doc)
 	return widget;
 }
 
-/**
- * Flags the SPSVGSPViewWidget to have its size renegotiated with Gtk.
- */
 void SPSVGSPViewWidget::setResize(bool resize, gdouble width, gdouble height)
 {
     g_return_if_fail( !resize || (width > 0.0) );
diff --git a/src/svg-view-widget.h b/src/svg-view-widget.h
index 0c2c651ad..d489ccbdd 100644
--- a/src/svg-view-widget.h
+++ b/src/svg-view-widget.h
@@ -24,9 +24,15 @@ class SPSVGSPViewWidgetClass;
 #define SP_IS_SVG_VIEW_WIDGET(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), SP_TYPE_SVG_VIEW_WIDGET))
 #define SP_IS_SVG_VIEW_WIDGET_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), SP_TYPE_SVG_VIEW_WIDGET))
 
-GType sp_svg_view_widget_get_type (void);
+/**
+ * Registers SPSVGSPViewWidget class with Gtk and returns its type number.
+ */
+GType sp_svg_view_widget_get_type(void);
 
-GtkWidget *sp_svg_view_widget_new (SPDocument *doc);
+/**
+ * Constructs new SPSVGSPViewWidget object and returns pointer to it.
+ */
+GtkWidget *sp_svg_view_widget_new(SPDocument *doc);
 
 /**
  * An SPSVGSPViewWidget is an SVG view together with a canvas.
@@ -43,7 +49,10 @@ public:
     gdouble maxwidth, maxheight;
 
     // C++ Wrappers
-    /// Flags the SPSVGSPViewWidget to have its size changed with Gtk.
+
+    /**
+     * Flags the SPSVGSPViewWidget to have its size renegotiated with Gtk.
+     */
     void setResize(bool resize, gdouble width, gdouble height);
 };
 
diff --git a/src/svg-view.cpp b/src/svg-view.cpp
index 8773dfab7..6eca02d5c 100644
--- a/src/svg-view.cpp
+++ b/src/svg-view.cpp
@@ -1,5 +1,5 @@
-/** \file
- * Functions and callbacks for generic SVG view and widget
+/*
+ * Functions and callbacks for generic SVG view and widget.
  *
  * Authors:
  *   Lauris Kaplinski <lauris@kaplinski.com>
@@ -21,10 +21,7 @@
 #include "svg-view.h"
 #include "sp-root.h"
 
-/**
- * Constructs new SPSVGView object and returns pointer to it.
- */
-SPSVGView::SPSVGView (SPCanvasGroup *parent)
+SPSVGView::SPSVGView(SPCanvasGroup *parent)
 {
     _hscale = 1.0;
     _vscale = 1.0;
@@ -47,11 +44,7 @@ SPSVGView::~SPSVGView()
     }
 }
 
-/**
- * Rescales SPSVGView to given proportions.
- */
-void
-SPSVGView::setScale (gdouble hscale, gdouble vscale)
+void SPSVGView::setScale(gdouble hscale, gdouble vscale)
 {
     if (!_rescale && ((hscale != _hscale) || (vscale != _vscale))) {
         _hscale = hscale;
@@ -60,12 +53,7 @@ SPSVGView::setScale (gdouble hscale, gdouble vscale)
     }
 }
 
-/**
- * Rescales SPSVGView and keeps aspect ratio.
- */
-void
-SPSVGView::setRescale
-(bool rescale, bool keepaspect, gdouble width, gdouble height)
+void SPSVGView::setRescale(bool rescale, bool keepaspect, gdouble width, gdouble height)
 {
     g_return_if_fail (!rescale || (width >= 0.0));
     g_return_if_fail (!rescale || (height >= 0.0));
@@ -78,15 +66,17 @@ SPSVGView::setRescale
     doRescale (true);
 }
 
-/**
- * Helper function that sets rescale ratio and emits resize event.
- */
-void
-SPSVGView::doRescale (bool event)
+void SPSVGView::doRescale(bool event)
 {
-    if (!doc()) return;
-    if (doc()->getWidth () < 1e-9) return;
-    if (doc()->getHeight () < 1e-9) return;
+    if (!doc()) {
+        return;
+    }
+    if (doc()->getWidth () < 1e-9) {
+        return;
+    }
+    if (doc()->getHeight () < 1e-9) {
+        return;
+    }
 
     if (_rescale) {
         _hscale = _width / doc()->getWidth ();
@@ -110,16 +100,14 @@ SPSVGView::doRescale (bool event)
     }
 }
 
-void
-SPSVGView::mouseover()
+void SPSVGView::mouseover()
 {
     GdkCursor *cursor = gdk_cursor_new(GDK_HAND2);
     gdk_window_set_cursor(GTK_WIDGET(SP_CANVAS_ITEM(_drawing)->canvas)->window, cursor);
     gdk_cursor_unref(cursor);
 }
 
-void
-SPSVGView::mouseout()
+void SPSVGView::mouseout()
 {
     gdk_window_set_cursor(GTK_WIDGET(SP_CANVAS_ITEM(_drawing)->canvas)->window, NULL);
 }
@@ -129,8 +117,7 @@ SPSVGView::mouseout()
  * Callback connected with arena_event.
  */
 /// \todo fixme.
-static gint
-arena_handler (SPCanvasArena */*arena*/, Inkscape::DrawingItem *ai, GdkEvent *event, SPSVGView *svgview)
+static gint arena_handler(SPCanvasArena */*arena*/, Inkscape::DrawingItem *ai, GdkEvent *event, SPSVGView *svgview)
 {
 	static gdouble x, y;
 	static gboolean active = FALSE;
@@ -185,11 +172,7 @@ arena_handler (SPCanvasArena */*arena*/, Inkscape::DrawingItem *ai, GdkEvent *ev
 	return TRUE;
 }
 
-/**
- * Callback connected with set_document signal.
- */
-void
-SPSVGView::setDocument (SPDocument *document)
+void SPSVGView::setDocument(SPDocument *document)
 {
     if (doc()) {
         doc()->getRoot()->invoke_hide(_dkey);
@@ -216,11 +199,7 @@ SPSVGView::setDocument (SPDocument *document)
     }
 }
 
-/**
- * Callback connected with document_resized signal.
- */
-void
-SPSVGView::onDocumentResized (gdouble width, gdouble height)
+void SPSVGView::onDocumentResized(gdouble width, gdouble height)
 {
     setScale (width, height);
     doRescale (!_rescale);
diff --git a/src/svg-view.h b/src/svg-view.h
index 5e830eb00..33a9b569a 100644
--- a/src/svg-view.h
+++ b/src/svg-view.h
@@ -33,29 +33,50 @@ public:
     gdouble         _height;
 
 
-    SPSVGView (SPCanvasGroup* parent);
+    /**
+     * Constructs new SPSVGView object and returns pointer to it.
+     */
+    SPSVGView(SPCanvasGroup* parent);
+
     virtual ~SPSVGView();
         
-    /// Rescales SPSVGView to given proportions.
-    void setScale (gdouble hscale, gdouble vscale);
+    /**
+     * Rescales SPSVGView to given proportions.
+     */
+    void setScale(gdouble hscale, gdouble vscale);
     
-    /// Rescales SPSVGView and keeps aspect ratio.
-    void setRescale (bool rescale, bool keepaspect, gdouble width, gdouble height);
+    /**
+     * Rescales SPSVGView and keeps aspect ratio.
+     */
+    void setRescale(bool rescale, bool keepaspect, gdouble width, gdouble height);
+
+    /**
+     * Helper function that sets rescale ratio and emits resize event.
+     */
+    void doRescale(bool event);
 
-    void doRescale (bool event);
+    /**
+     * Callback connected with set_document signal.
+     */
+    virtual void setDocument(SPDocument *document);
 
-    virtual void setDocument (SPDocument*);
     virtual void mouseover();
+
     virtual void mouseout();
+
     virtual bool shutdown() { return true; }
 
 private:
-    virtual void onPositionSet (double, double) {}
-    virtual void onResized (double, double) {}
+    virtual void onPositionSet(double, double) {}
+    virtual void onResized(double, double) {}
     virtual void onRedrawRequested() {}
-    virtual void onStatusMessage (Inkscape::MessageType /*type*/, gchar const */*message*/) {}
-    virtual void onDocumentURISet (gchar const* /*uri*/) {}
-    virtual void onDocumentResized (double, double);
+    virtual void onStatusMessage(Inkscape::MessageType /*type*/, gchar const */*message*/) {}
+    virtual void onDocumentURISet(gchar const* /*uri*/) {}
+
+    /**
+     * Callback connected with document_resized signal.
+     */
+    virtual void onDocumentResized(double, double);
 };
 
 #endif // SEEN_SP_SVG_VIEW_H
diff --git a/src/trace/trace.cpp b/src/trace/trace.cpp
index 64a4a7732..8f04d7a2d 100644
--- a/src/trace/trace.cpp
+++ b/src/trace/trace.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * A generic interface for plugging different
  *  autotracers into Inkscape.
  *
@@ -38,12 +38,7 @@
 namespace Inkscape {
 namespace Trace {
 
-/**
- * Get the selected image.  Also check for any SPItems over it, in
- * case the user wants SIOX pre-processing.
- */
-SPImage *
-Tracer::getSelectedSPImage()
+SPImage *Tracer::getSelectedSPImage()
 {
 
     SPDesktop *desktop = SP_ACTIVE_DESKTOP;
@@ -198,13 +193,7 @@ public:
 
 
 
-/**
- * Process a GdkPixbuf, according to which areas have been
- * obscured in the GUI.
- */
-Glib::RefPtr<Gdk::Pixbuf>
-Tracer::sioxProcessImage(SPImage *img,
-             Glib::RefPtr<Gdk::Pixbuf>origPixbuf)
+Glib::RefPtr<Gdk::Pixbuf> Tracer::sioxProcessImage(SPImage *img, Glib::RefPtr<Gdk::Pixbuf>origPixbuf)
 {
     if (!sioxEnabled)
         return origPixbuf;
@@ -334,11 +323,7 @@ Tracer::sioxProcessImage(SPImage *img,
 }
 
 
-/**
- *
- */
-Glib::RefPtr<Gdk::Pixbuf>
-Tracer::getSelectedImage()
+Glib::RefPtr<Gdk::Pixbuf> Tracer::getSelectedImage()
 {
 
 
@@ -378,18 +363,12 @@ Tracer::getSelectedImage()
 //#  T R A C E
 //#########################################################################
 
-/**
- *  Whether we want to enable SIOX subimage selection
- */
 void Tracer::enableSiox(bool enable)
 {
     sioxEnabled = enable;
 }
 
 
-/**
- *  Threaded method that does single bitmap--->path conversion
- */
 void Tracer::traceThread()
 {
     //## Remember. NEVER leave this method without setting
@@ -559,9 +538,6 @@ void Tracer::traceThread()
 
 
 
-/**
- *  Main tracing method
- */
 void Tracer::trace(TracingEngine *theEngine)
 {
     //Check if we are already running
@@ -588,9 +564,6 @@ void Tracer::trace(TracingEngine *theEngine)
 
 
 
-/**
- *  Abort the thread that is executing trace()
- */
 void Tracer::abort()
 {
 
diff --git a/src/trace/trace.h b/src/trace/trace.h
index 45b18385f..29b8716ee 100644
--- a/src/trace/trace.h
+++ b/src/trace/trace.h
@@ -6,8 +6,8 @@
  *
  * Released under GNU GPL, read the file 'COPYING' for more information
  */
-#ifndef __TRACE_H__
-#define __TRACE_H__
+#ifndef SEEN_TRACE_H
+#define SEEN_TRACE_H
 
 #ifdef HAVE_CONFIG_H
 # include "config.h"
@@ -207,7 +207,7 @@ public:
     void abort();
 
     /**
-     *  Whether we want to enable SIOX subimage selection
+     *  Whether we want to enable SIOX subimage selection.
      */
     void enableSiox(bool enable);
 
@@ -216,6 +216,7 @@ private:
 
     /**
      * This is the single path code that is called by its counterpart above.
+     * Threaded method that does single bitmap--->path conversion.
      */
     void traceThread();
 
@@ -231,14 +232,21 @@ private:
      */
     TracingEngine *engine;
 
+    /**
+     * Get the selected image.  Also check for any SPItems over it, in
+     * case the user wants SIOX pre-processing.
+     */
     SPImage *getSelectedSPImage();
 
     std::vector<SPShape *> sioxShapes;
 
     bool sioxEnabled;
 
-    Glib::RefPtr<Gdk::Pixbuf> sioxProcessImage(
-           SPImage *img, Glib::RefPtr<Gdk::Pixbuf> origPixbuf);
+    /**
+     * Process a GdkPixbuf, according to which areas have been
+     * obscured in the GUI.
+     */
+    Glib::RefPtr<Gdk::Pixbuf> sioxProcessImage(SPImage *img, Glib::RefPtr<Gdk::Pixbuf> origPixbuf);
 
     Glib::RefPtr<Gdk::Pixbuf> lastSioxPixbuf;
     Glib::RefPtr<Gdk::Pixbuf> lastOrigPixbuf;
@@ -254,7 +262,7 @@ private:
 
 
 
-#endif //__TRACE_H__
+#endif // SEEN_TRACE_H
 
 //#########################################################################
 //# E N D   O F   F I L E
diff --git a/src/ui/dialog/desktop-tracker.cpp b/src/ui/dialog/desktop-tracker.cpp
index 4eeac74b9..42447a141 100644
--- a/src/ui/dialog/desktop-tracker.cpp
+++ b/src/ui/dialog/desktop-tracker.cpp
@@ -1,7 +1,3 @@
-/**
- * Glyph selector dialog.
- */
-
 /* Authors:
  *   Jon A. Cruz
  *
diff --git a/src/ui/dialog/desktop-tracker.h b/src/ui/dialog/desktop-tracker.h
index d73071194..da276fae4 100644
--- a/src/ui/dialog/desktop-tracker.h
+++ b/src/ui/dialog/desktop-tracker.h
@@ -1,7 +1,3 @@
-/**
- * Glyph selector dialog.
- */
-
 /* Authors:
  *   Jon A. Cruz
  *
diff --git a/src/ui/dialog/find.cpp b/src/ui/dialog/find.cpp
index 78bb8c66a..49bdc0a30 100644
--- a/src/ui/dialog/find.cpp
+++ b/src/ui/dialog/find.cpp
@@ -1,6 +1,4 @@
-/**
- * Find dialog.
- *
+/*
  * Authors:
  *   Bryce W. Harrington <bryce@bryceharrington.org>
  *   Johan Engelen <goejendaagh@zonnet.nl>
diff --git a/src/ui/view/view-widget.cpp b/src/ui/view/view-widget.cpp
index d43877569..7876928f7 100644
--- a/src/ui/view/view-widget.cpp
+++ b/src/ui/view/view-widget.cpp
@@ -1,6 +1,4 @@
-/** \file
- * SPViewWidget implementation.
- *
+/*
  * Authors:
  *   Lauris Kaplinski <lauris@kaplinski.com>
  *   Ralf Stephan <ralf@ark.in-berlin.de>
@@ -16,7 +14,7 @@
 
 //using namespace Inkscape::UI::View;
 
-/* SPViewWidget */
+// SPViewWidget
 
 static void sp_view_widget_class_init(SPViewWidgetClass *vwc);
 static void sp_view_widget_init(SPViewWidget *widget);
@@ -24,9 +22,6 @@ static void sp_view_widget_destroy(GtkObject *object);
 
 static GtkEventBoxClass *widget_parent_class;
 
-/**
- * Registers the SPViewWidget class with Glib and returns its type number.
- */
 GType sp_view_widget_get_type(void)
 {
     static GType type = 0;
@@ -89,10 +84,6 @@ static void sp_view_widget_destroy(GtkObject *object)
     Inkscape::GC::request_early_collection();
 }
 
-/**
- * Connects widget to view's 'resized' signal and calls virtual set_view()
- * function.
- */
 void sp_view_widget_set_view(SPViewWidget *vw, Inkscape::UI::View::View *view)
 {
     g_return_if_fail(vw != NULL);
@@ -109,9 +100,6 @@ void sp_view_widget_set_view(SPViewWidget *vw, Inkscape::UI::View::View *view)
     }
 }
 
-/**
- * Calls the virtual shutdown() function of the SPViewWidget.
- */
 bool sp_view_widget_shutdown(SPViewWidget *vw)
 {
     g_return_val_if_fail(vw != NULL, TRUE);
diff --git a/src/ui/view/view-widget.h b/src/ui/view/view-widget.h
index 5143054d2..668f9d19a 100644
--- a/src/ui/view/view-widget.h
+++ b/src/ui/view/view-widget.h
@@ -33,15 +33,27 @@ class SPNamedView;
 #define SP_VIEW_WIDGET_VIEW(w) (SP_VIEW_WIDGET (w)->view)
 #define SP_VIEW_WIDGET_DOCUMENT(w) (SP_VIEW_WIDGET (w)->view ? ((SPViewWidget *) (w))->view->doc : NULL)
 
-GType sp_view_widget_get_type (void);
+/**
+ * Registers the SPViewWidget class with Glib and returns its type number.
+ */
+GType sp_view_widget_get_type(void);
 
-void sp_view_widget_set_view (SPViewWidget *vw, Inkscape::UI::View::View *view);
+/**
+ * Connects widget to view's 'resized' signal and calls virtual set_view()
+ * function.
+ */
+void sp_view_widget_set_view(SPViewWidget *vw, Inkscape::UI::View::View *view);
 
-/// Allows presenting 'save changes' dialog, FALSE - continue, TRUE - cancel
-bool sp_view_widget_shutdown (SPViewWidget *vw);
+/**
+ * Allows presenting 'save changes' dialog, FALSE - continue, TRUE - cancel.
+ * Calls the virtual shutdown() function of the SPViewWidget.
+ */
+bool sp_view_widget_shutdown(SPViewWidget *vw);
 
-/// Create a new SPViewWidget (which happens to be a SPDesktopWidget). 
-SPViewWidget *sp_desktop_widget_new (SPNamedView *namedview);
+/**
+ * Create a new SPViewWidget (which happens to be a SPDesktopWidget).
+ */
+SPViewWidget *sp_desktop_widget_new(SPNamedView *namedview);
 
 /**
  * SPViewWidget is a GUI widget that contain a single View. It is also
diff --git a/src/ui/view/view.cpp b/src/ui/view/view.cpp
index dc6307ab0..e13976cc4 100644
--- a/src/ui/view/view.cpp
+++ b/src/ui/view/view.cpp
@@ -1,6 +1,4 @@
-/** \file
- * View implementation
- *
+/*
  * Authors:
  *   Lauris Kaplinski <lauris@kaplinski.com>
  *   Ralf Stephan <ralf@ark.in-berlin.de>
@@ -78,9 +76,6 @@ View::View()
     _message_changed_connection = _message_stack->connectChanged (sigc::bind (sigc::ptr_fun (&_onStatusMessage), this));
 }
 
-/**
- * Deletes and nulls all View message stacks and disconnects it from signals.
- */
 View::~View()
 {
     _close();
@@ -127,15 +122,6 @@ void View::requestRedraw()
     _redraw_requested_signal.emit();
 }
 
-/**
- * Disconnects the view from the document signals, connects the view 
- * to a new one, and emits the _document_set_signal on the view.
- *
- * This is code comon to all subclasses and called from their
- * setDocument() methods after they are done.
- * 
- * \param doc The new document to connect the view to.
- */
 void View::setDocument(SPDocument *doc) {
     g_return_if_fail(doc != NULL);
 
diff --git a/src/ui/view/view.h b/src/ui/view/view.h
index 8b30aead2..6ed9f476c 100644
--- a/src/ui/view/view.h
+++ b/src/ui/view/view.h
@@ -72,6 +72,10 @@ class View : public GC::Managed<>,
 public:
 
     View();
+
+    /**
+     * Deletes and nulls all View message stacks and disconnects it from signals.
+     */
     virtual ~View();
 
     void close() { _close(); }
@@ -110,6 +114,16 @@ protected:
     Inkscape::MessageContext *_tips_message_context;
 
     virtual void _close();
+
+    /**
+     * Disconnects the view from the document signals, connects the view 
+     * to a new one, and emits the _document_set_signal on the view.
+     *
+     * This is code comon to all subclasses and called from their
+     * setDocument() methods after they are done.
+     * 
+     * @param doc The new document to connect the view to.
+     */
     virtual void setDocument(SPDocument *doc);
 
     sigc::signal<void,double,double>   _position_set_signal;
diff --git a/src/ui/widget/button.cpp b/src/ui/widget/button.cpp
index fe4aa90ce..ae1dbbe98 100644
--- a/src/ui/widget/button.cpp
+++ b/src/ui/widget/button.cpp
@@ -1,6 +1,4 @@
-/**
- * Button and CheckButton widgets.
- *
+/*
  * Author:
  *   buliabyak@gmail.com
  *
diff --git a/src/ui/widget/color-picker.cpp b/src/ui/widget/color-picker.cpp
index bd7a666d2..f32e25885 100644
--- a/src/ui/widget/color-picker.cpp
+++ b/src/ui/widget/color-picker.cpp
@@ -1,7 +1,4 @@
-/**
- * @file
- * Color picker button & window.
- *
+/*
  * Authors:
  *   Lauris Kaplinski <lauris@kaplinski.com>
  *   bulia byak <buliabyak@users.sf.net>
diff --git a/src/ui/widget/color-preview.cpp b/src/ui/widget/color-preview.cpp
index a4212c7ba..22ca1ebe0 100644
--- a/src/ui/widget/color-preview.cpp
+++ b/src/ui/widget/color-preview.cpp
@@ -1,6 +1,4 @@
-/** \file
- * Implemenmtation of a simple color preview widget
- *
+/*
  * Author:
  *   Lauris Kaplinski <lauris@kaplinski.com>
  *   Ralf Stephan <ralf@ark.in-berlin.de>
diff --git a/src/ui/widget/dock-item.cpp b/src/ui/widget/dock-item.cpp
index 9c6758bc0..14b219110 100644
--- a/src/ui/widget/dock-item.cpp
+++ b/src/ui/widget/dock-item.cpp
@@ -1,6 +1,4 @@
-/**
- * A custom Inkscape wrapper around gdl_dock_item.
- *
+/*
  * Author:
  *   Gustav Broberg <broberg@kth.se>
  *
diff --git a/src/ui/widget/entity-entry.cpp b/src/ui/widget/entity-entry.cpp
index e62eb009c..aaf67a7a2 100644
--- a/src/ui/widget/entity-entry.cpp
+++ b/src/ui/widget/entity-entry.cpp
@@ -1,5 +1,4 @@
-/** \file
- *
+/*
  * Authors:
  *   bulia byak <buliabyak@users.sf.net>
  *   Bryce W. Harrington <bryce@bryceharrington.org>
diff --git a/src/ui/widget/entry.cpp b/src/ui/widget/entry.cpp
index ce7552fd6..7ac8532fb 100644
--- a/src/ui/widget/entry.cpp
+++ b/src/ui/widget/entry.cpp
@@ -1,8 +1,4 @@
-/**
- * @file
- *
- * Helperclass for Gtk::Entry widgets.
- *
+/*
  * Authors:
  *   Johan Engelen <goejendaagh@zonnet.nl>
  *
diff --git a/src/ui/widget/handlebox.cpp b/src/ui/widget/handlebox.cpp
index f5b716975..0ac84ef3a 100644
--- a/src/ui/widget/handlebox.cpp
+++ b/src/ui/widget/handlebox.cpp
@@ -1,10 +1,4 @@
-/**
- * HandleBox Widget - Adds a detachment handle to another widget.
- *
- * This work really doesn't amount to much more than a convenience constructor
- * for Gtk::HandleBox.  Maybe this could be contributed back to Gtkmm, as
- * Gtkmm provides several convenience constructors for other widgets as well.
- *
+/*
  * Author:
  *   Derek P. Moore <derekm@hackunix.org>
  *
diff --git a/src/ui/widget/icon-widget.cpp b/src/ui/widget/icon-widget.cpp
index c3780b616..1bc4ad308 100644
--- a/src/ui/widget/icon-widget.cpp
+++ b/src/ui/widget/icon-widget.cpp
@@ -1,6 +1,4 @@
-/**
- * Icon Widget.
- *
+/*
  * Author:
  *   Bryce Harrington <bryce@bryceharrington.org>
  *
@@ -21,14 +19,6 @@ namespace Inkscape {
 namespace UI {
 namespace Widget {
 
-/**
- *    General purpose icon widget, supporting SVG, etc. icon loading
- *
- *    \param ...
- *
- *    An icon widget is a ...
- */
-
 IconWidget::IconWidget()
 {
     _pb = NULL;
diff --git a/src/ui/widget/labelled.cpp b/src/ui/widget/labelled.cpp
index a62d1a470..0a13d6347 100644
--- a/src/ui/widget/labelled.cpp
+++ b/src/ui/widget/labelled.cpp
@@ -1,7 +1,4 @@
-/**
- * Labelled Widget - Adds a label with optional icon or suffix to
- *        another widget.
- *
+/*
  * Authors:
  *   Carl Hetherington <inkscape@carlh.net>
  *   Derek P. Moore <derekm@hackunix.org>
@@ -24,18 +21,6 @@ namespace Inkscape {
 namespace UI {
 namespace Widget {
 
-/**
- * Construct a Labelled Widget.
- *
- * \param label     Label.
- * \param widget    Widget to label; should be allocated with new, as it will
- *                  be passed to Gtk::manage().
- * \param suffix    Suffix, placed after the widget (defaults to "").
- * \param icon      Icon filename, placed before the label (defaults to "").
- * \param mnemonic  Mnemonic toggle; if true, an underscore (_) in the text
- *                  indicates the next character should be used for the
- *                  mnemonic accelerator key (defaults to true).
- */
 Labelled::Labelled(Glib::ustring const &label, Glib::ustring const &tooltip,
                    Gtk::Widget *widget,
                    Glib::ustring const &suffix,
@@ -60,9 +45,6 @@ Labelled::Labelled(Glib::ustring const &label, Glib::ustring const &tooltip,
 }
 
 
-/**
- * Allow the setting of the width of the labelled widget
- */
 void Labelled::setWidgetSizeRequest(int width, int height)
 {
     if (_widget)
diff --git a/src/ui/widget/labelled.h b/src/ui/widget/labelled.h
index 9614dc28a..8c2ec8939 100644
--- a/src/ui/widget/labelled.h
+++ b/src/ui/widget/labelled.h
@@ -26,6 +26,19 @@ namespace Widget {
 class Labelled : public Gtk::HBox
 {
 public:
+
+    /**
+     * Construct a Labelled Widget.
+     *
+     * @param label     Label.
+     * @param widget    Widget to label; should be allocated with new, as it will
+     *                  be passed to Gtk::manage().
+     * @param suffix    Suffix, placed after the widget (defaults to "").
+     * @param icon      Icon filename, placed before the label (defaults to "").
+     * @param mnemonic  Mnemonic toggle; if true, an underscore (_) in the text
+     *                  indicates the next character should be used for the
+     *                  mnemonic accelerator key (defaults to true).
+     */
     Labelled(Glib::ustring const &label, Glib::ustring const &tooltip,
              Gtk::Widget *widget,
              Glib::ustring const &suffix = "",
diff --git a/src/ui/widget/licensor.cpp b/src/ui/widget/licensor.cpp
index c9550bb27..9cb904c9f 100644
--- a/src/ui/widget/licensor.cpp
+++ b/src/ui/widget/licensor.cpp
@@ -1,5 +1,4 @@
-/** \file
- *
+/*
  * Authors:
  *   bulia byak <buliabyak@users.sf.net>
  *   Bryce W. Harrington <bryce@bryceharrington.org>
diff --git a/src/ui/widget/notebook-page.cpp b/src/ui/widget/notebook-page.cpp
index eea8aefba..92bcb6937 100644
--- a/src/ui/widget/notebook-page.cpp
+++ b/src/ui/widget/notebook-page.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Notebook page widget.
  *
  * Author:
@@ -19,12 +19,6 @@ namespace Inkscape {
 namespace UI {
 namespace Widget {
 
-/**
- *    Construct a NotebookPage
- *
- *    \param label Label.
- */
-  
 NotebookPage::NotebookPage(int n_rows, int n_columns, bool expand, bool fill, guint padding)
     :_table(n_rows, n_columns)
 {
diff --git a/src/ui/widget/notebook-page.h b/src/ui/widget/notebook-page.h
index bd53870d6..a541f3ba0 100644
--- a/src/ui/widget/notebook-page.h
+++ b/src/ui/widget/notebook-page.h
@@ -24,7 +24,12 @@ namespace Widget {
 class NotebookPage : public Gtk::VBox
 {
 public:
+
     NotebookPage();
+
+    /**
+     * Construct a NotebookPage.
+     */
     NotebookPage(int n_rows, int n_columns, bool expand=false, bool fill=false, guint padding=0);
 
     Gtk::Table& table() { return _table; }
diff --git a/src/ui/widget/page-sizer.cpp b/src/ui/widget/page-sizer.cpp
index 67f3789c7..a6b0fb76d 100644
--- a/src/ui/widget/page-sizer.cpp
+++ b/src/ui/widget/page-sizer.cpp
@@ -1,7 +1,9 @@
-/** \file
+/**
+ * @file
  *
  * Paper-size widget and helper functions
- *
+ */
+/*
  * Authors:
  *   bulia byak <buliabyak@users.sf.net>
  *   Lauris Kaplinski <lauris@kaplinski.com>
diff --git a/src/ui/widget/panel.cpp b/src/ui/widget/panel.cpp
index aaa8e2a70..8c8603640 100644
--- a/src/ui/widget/panel.cpp
+++ b/src/ui/widget/panel.cpp
@@ -1,6 +1,4 @@
-/**
- * Panel widget.
- *
+/*
  * Authors:
  *   Bryce Harrington <bryce@bryceharrington.org>
  *   Jon A. Cruz <jon@joncruz.org>
@@ -54,10 +52,6 @@ void Panel::prep() {
     eek_preview_set_size_mappings( G_N_ELEMENTS(sizes), sizes );
 }
 
-/**
- *    Construct a Panel
- */
-
 Panel::Panel(Glib::ustring const &label, gchar const *prefs_path,
              int verb_num, Glib::ustring const &apply_label,
              bool menu_desired) :
diff --git a/src/ui/widget/panel.h b/src/ui/widget/panel.h
index 3134111c0..d51d942dd 100644
--- a/src/ui/widget/panel.h
+++ b/src/ui/widget/panel.h
@@ -41,11 +41,15 @@ class Panel : public Gtk::VBox {
 public:
     static void prep();
 
-    virtual ~Panel();
+    /**
+     * Construct a Panel.
+     */
     Panel(Glib::ustring const &label = "", gchar const *prefs_path = 0,
           int verb_num = 0, Glib::ustring const &apply_label = "",
           bool menu_desired = false);
 
+    virtual ~Panel();
+
     gchar const *getPrefsPath() const;
     void setLabel(Glib::ustring const &label);
     Glib::ustring const &getLabel() const;
diff --git a/src/ui/widget/point.cpp b/src/ui/widget/point.cpp
index 7a4b4459a..385b60122 100644
--- a/src/ui/widget/point.cpp
+++ b/src/ui/widget/point.cpp
@@ -1,7 +1,4 @@
-/**
- * Point Widget - A labelled text box, with spin buttons and optional
- *        icon or suffix, for entering arbitrary coordinate values.
- *
+/*
  * Authors:
  *   Johan Engelen <j.b.c.engelen@utwente.nl>
  *   Carl Hetherington <inkscape@carlh.net>
@@ -28,16 +25,6 @@ namespace Inkscape {
 namespace UI {
 namespace Widget {
 
-/**
- * Construct a Point Widget.
- *
- * \param label     Label.
- * \param suffix    Suffix, placed after the widget (defaults to "").
- * \param icon      Icon filename, placed before the label (defaults to "").
- * \param mnemonic  Mnemonic toggle; if true, an underscore (_) in the label
- *                  indicates the next character should be used for the
- *                  mnemonic accelerator key (defaults to false).
- */
 Point::Point(Glib::ustring const &label, Glib::ustring const &tooltip,
                Glib::ustring const &suffix,
                Glib::ustring const &icon,
@@ -51,17 +38,6 @@ Point::Point(Glib::ustring const &label, Glib::ustring const &tooltip,
     static_cast<Gtk::VBox*>(_widget)->show_all_children();
 }
 
-/**
- * Construct a Point Widget.
- *
- * \param label     Label.
- * \param digits    Number of decimal digits to display.
- * \param suffix    Suffix, placed after the widget (defaults to "").
- * \param icon      Icon filename, placed before the label (defaults to "").
- * \param mnemonic  Mnemonic toggle; if true, an underscore (_) in the label
- *                  indicates the next character should be used for the
- *                  mnemonic accelerator key (defaults to false).
- */
 Point::Point(Glib::ustring const &label, Glib::ustring const &tooltip,
                unsigned digits,
                Glib::ustring const &suffix,
@@ -76,18 +52,6 @@ Point::Point(Glib::ustring const &label, Glib::ustring const &tooltip,
     static_cast<Gtk::VBox*>(_widget)->show_all_children();
 }
 
-/**
- * Construct a Point Widget.
- *
- * \param label     Label.
- * \param adjust    Adjustment to use for the SpinButton.
- * \param digits    Number of decimal digits to display (defaults to 0).
- * \param suffix    Suffix, placed after the widget (defaults to "").
- * \param icon      Icon filename, placed before the label (defaults to "").
- * \param mnemonic  Mnemonic toggle; if true, an underscore (_) in the label
- *                  indicates the next character should be used for the
- *                  mnemonic accelerator key (defaults to true).
- */
 Point::Point(Glib::ustring const &label, Glib::ustring const &tooltip,
                Gtk::Adjustment &adjust,
                unsigned digits,
@@ -103,131 +67,105 @@ Point::Point(Glib::ustring const &label, Glib::ustring const &tooltip,
     static_cast<Gtk::VBox*>(_widget)->show_all_children();
 }
 
-/** Fetches the precision of the spin buton */
-unsigned
-Point::getDigits() const
+unsigned Point::getDigits() const
 {
     return xwidget.getDigits();
 }
 
-/** Gets the current step ingrement used by the spin button */
-double
-Point::getStep() const
+double Point::getStep() const
 {
     return xwidget.getStep();
 }
 
-/** Gets the current page increment used by the spin button */
-double
-Point::getPage() const
+double Point::getPage() const
 {
     return xwidget.getPage();
 }
 
-/** Gets the minimum range value allowed for the spin button */
-double
-Point::getRangeMin() const
+double Point::getRangeMin() const
 {
     return xwidget.getRangeMin();
 }
 
-/** Gets the maximum range value allowed for the spin button */
-double
-Point::getRangeMax() const
+double Point::getRangeMax() const
 {
     return xwidget.getRangeMax();
 }
 
-/** Get the value in the spin_button . */
-double
-Point::getXValue() const
+double Point::getXValue() const
 {
     return xwidget.getValue();
 }
-double
-Point::getYValue() const
+
+double Point::getYValue() const
 {
     return ywidget.getValue();
 }
-Geom::Point
-Point::getValue() const
+
+Geom::Point Point::getValue() const
 {
     return Geom::Point( getXValue() , getYValue() );
 }
 
-/** Get the value spin_button represented as an integer. */
-int
-Point::getXValueAsInt() const
+int Point::getXValueAsInt() const
 {
     return xwidget.getValueAsInt();
 }
-int
-Point::getYValueAsInt() const
+
+int Point::getYValueAsInt() const
 {
     return ywidget.getValueAsInt();
 }
 
 
-/** Sets the precision to be displayed by the spin button */
-void
-Point::setDigits(unsigned digits)
+void Point::setDigits(unsigned digits)
 {
     xwidget.setDigits(digits);
     ywidget.setDigits(digits);
 }
 
-/** Sets the step and page increments for the spin button */
-void
-Point::setIncrements(double step, double page)
+void Point::setIncrements(double step, double page)
 {
     xwidget.setIncrements(step, page);
     ywidget.setIncrements(step, page);
 }
 
-/** Sets the minimum and maximum range allowed for the spin button */
-void
-Point::setRange(double min, double max)
+void Point::setRange(double min, double max)
 {
     xwidget.setRange(min, max);
     ywidget.setRange(min, max);
 }
 
-/** Sets the value of the spin button */
-void
-Point::setValue(Geom::Point const & p)
+void Point::setValue(Geom::Point const & p)
 {
     xwidget.setValue(p[0]);
     ywidget.setValue(p[1]);
 }
 
-/** Manually forces an update of the spin button */
-void
-Point::update() {
+void Point::update()
+{
     xwidget.update();
     ywidget.update();
 }
 
-/** Check 'setProgrammatically' of both scalar widgets.   False if value is changed by user by clicking the widget. */
-bool
-Point::setProgrammatically() {
+bool Point::setProgrammatically() 
+{
     return (xwidget.setProgrammatically || ywidget.setProgrammatically);
 }
 
-void
-Point::clearProgrammatically() {
+void Point::clearProgrammatically()
+{
     xwidget.setProgrammatically = false;
     ywidget.setProgrammatically = false;
 }
 
 
-/** Signal raised when the spin button's value changes */
-Glib::SignalProxy0<void>
-Point::signal_x_value_changed()
+Glib::SignalProxy0<void> Point::signal_x_value_changed()
 {
     return xwidget.signal_value_changed();
 }
-Glib::SignalProxy0<void>
-Point::signal_y_value_changed()
+
+Glib::SignalProxy0<void> Point::signal_y_value_changed()
 {
     return ywidget.signal_value_changed();
 }
diff --git a/src/ui/widget/point.h b/src/ui/widget/point.h
index 651c8c8fb..ced43c47a 100644
--- a/src/ui/widget/point.h
+++ b/src/ui/widget/point.h
@@ -30,17 +30,54 @@ namespace Widget {
 class Point : public Labelled
 {
 public:
+
+
+    /**
+     * Construct a Point Widget.
+     *
+     * @param label     Label.
+     * @param suffix    Suffix, placed after the widget (defaults to "").
+     * @param icon      Icon filename, placed before the label (defaults to "").
+     * @param mnemonic  Mnemonic toggle; if true, an underscore (_) in the label
+     *                  indicates the next character should be used for the
+     *                  mnemonic accelerator key (defaults to false).
+     */
     Point( Glib::ustring const &label,
            Glib::ustring const &tooltip,
            Glib::ustring const &suffix = "",
            Glib::ustring const &icon = "",
            bool mnemonic = true);
+
+    /**
+     * Construct a Point Widget.
+     *
+     * @param label     Label.
+     * @param digits    Number of decimal digits to display.
+     * @param suffix    Suffix, placed after the widget (defaults to "").
+     * @param icon      Icon filename, placed before the label (defaults to "").
+     * @param mnemonic  Mnemonic toggle; if true, an underscore (_) in the label
+     *                  indicates the next character should be used for the
+     *                  mnemonic accelerator key (defaults to false).
+     */
     Point( Glib::ustring const &label,
            Glib::ustring const &tooltip,
            unsigned digits,
            Glib::ustring const &suffix = "",
            Glib::ustring const &icon = "",
            bool mnemonic = true);
+
+    /**
+     * Construct a Point Widget.
+     *
+     * @param label     Label.
+     * @param adjust    Adjustment to use for the SpinButton.
+     * @param digits    Number of decimal digits to display (defaults to 0).
+     * @param suffix    Suffix, placed after the widget (defaults to "").
+     * @param icon      Icon filename, placed before the label (defaults to "").
+     * @param mnemonic  Mnemonic toggle; if true, an underscore (_) in the label
+     *                  indicates the next character should be used for the
+     *                  mnemonic accelerator key (defaults to true).
+     */
     Point( Glib::ustring const &label,
            Glib::ustring const &tooltip,
            Gtk::Adjustment &adjust,
@@ -49,35 +86,93 @@ public:
            Glib::ustring const &icon = "",
            bool mnemonic = true);
 
+    /**
+     * Fetches the precision of the spin buton.
+     */
     unsigned getDigits() const;
+
+    /**
+     * Gets the current step ingrement used by the spin button.
+     */
     double  getStep() const;
+
+    /**
+     * Gets the current page increment used by the spin button.
+     */
     double  getPage() const;
+
+    /**
+     * Gets the minimum range value allowed for the spin button.
+     */
     double  getRangeMin() const;
+
+    /**
+     * Gets the maximum range value allowed for the spin button.
+     */
     double  getRangeMax() const;
+
     bool    getSnapToTicks() const;
+
+    /**
+     * Get the value in the spin_button.
+     */
     double  getXValue() const;
+
     double  getYValue() const;
+
     Geom::Point getValue() const;
+
+    /**
+     * Get the value spin_button represented as an integer.
+     */
     int     getXValueAsInt() const;
+
     int     getYValueAsInt() const;
 
+    /**
+     * Sets the precision to be displayed by the spin button.
+     */
     void    setDigits(unsigned digits);
+
+    /**
+     * Sets the step and page increments for the spin button.
+     */
     void    setIncrements(double step, double page);
+
+    /**
+     * Sets the minimum and maximum range allowed for the spin button.
+     */
     void    setRange(double min, double max);
+
+    /**
+     * Sets the value of the spin button.
+     */
     void    setValue(Geom::Point const & p);
 
+    /**
+     * Manually forces an update of the spin button.
+     */
     void    update();
 
+    /**
+     * Signal raised when the spin button's value changes.
+     */
     Glib::SignalProxy0<void> signal_x_value_changed();
+
     Glib::SignalProxy0<void> signal_y_value_changed();
 
-    bool setProgrammatically(); // true if the value was set by setValue, not changed by the user; 
-                                // if a callback checks it, it must reset it back to false
+    /**
+     * Check 'setProgrammatically' of both scalar widgets.   False if value is changed by user by clicking the widget.
+     * true if the value was set by setValue, not changed by the user;
+     * if a callback checks it, it must reset it back to false.
+     */
+    bool setProgrammatically();
+
     void clearProgrammatically();
 
 protected:
-    Scalar xwidget, ywidget;
-
+    Scalar xwidget;
+    Scalar ywidget;
 };
 
 } // namespace Widget
diff --git a/src/ui/widget/preferences-widget.cpp b/src/ui/widget/preferences-widget.cpp
index b88123ab1..001d2277d 100644
--- a/src/ui/widget/preferences-widget.cpp
+++ b/src/ui/widget/preferences-widget.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Inkscape Preferences dialog.
  *
  * Authors:
@@ -583,10 +583,6 @@ void PrefCombo::init(Glib::ustring const &prefs_path,
     this->set_active(row);
 }
 
-/**
-    initialize a combo box
-    second form uses strings as key values
-*/
 void PrefCombo::init(Glib::ustring const &prefs_path,
                      Glib::ustring labels[], Glib::ustring values[], int num_items, Glib::ustring default_value)
 {
diff --git a/src/ui/widget/preferences-widget.h b/src/ui/widget/preferences-widget.h
index 83290a045..ea5c377a3 100644
--- a/src/ui/widget/preferences-widget.h
+++ b/src/ui/widget/preferences-widget.h
@@ -164,6 +164,11 @@ class PrefCombo : public Gtk::ComboBoxText
 public:
     void init(Glib::ustring const &prefs_path,
               Glib::ustring labels[], int values[], int num_items, int default_value);
+
+    /**
+     * Initialize a combo box.
+     * second form uses strings as key values.
+     */
     void init(Glib::ustring const &prefs_path,
               Glib::ustring labels[], Glib::ustring values[], int num_items, Glib::ustring default_value);
 protected:
diff --git a/src/ui/widget/random.cpp b/src/ui/widget/random.cpp
index e2fb30812..03cea7d5a 100644
--- a/src/ui/widget/random.cpp
+++ b/src/ui/widget/random.cpp
@@ -1,10 +1,4 @@
-/**
- * Scalar Widget - A labelled text box, with spin buttons and optional
- *        icon or suffix, for entering arbitrary number values. It adds an extra
- *       number called "startseed", that is not UI edittable, but should be put in SVG.
- *      This does NOT generate a random number, but provides merely the saving of 
- *      the startseed value.
- *
+/*
  * Authors:
  *   Carl Hetherington <inkscape@carlh.net>
  *   Derek P. Moore <derekm@hackunix.org>
@@ -31,16 +25,6 @@ namespace Inkscape {
 namespace UI {
 namespace Widget {
 
-/**
- * Construct a Random scalar Widget.
- *
- * \param label     Label.
- * \param suffix    Suffix, placed after the widget (defaults to "").
- * \param icon      Icon filename, placed before the label (defaults to "").
- * \param mnemonic  Mnemonic toggle; if true, an underscore (_) in the label
- *                  indicates the next character should be used for the
- *                  mnemonic accelerator key (defaults to false).
- */
 Random::Random(Glib::ustring const &label, Glib::ustring const &tooltip,
                Glib::ustring const &suffix,
                Glib::ustring const &icon,
@@ -51,17 +35,6 @@ Random::Random(Glib::ustring const &label, Glib::ustring const &tooltip,
     addReseedButton();
 }
 
-/**
- * Construct a  Random Scalar Widget.
- *
- * \param label     Label.
- * \param digits    Number of decimal digits to display.
- * \param suffix    Suffix, placed after the widget (defaults to "").
- * \param icon      Icon filename, placed before the label (defaults to "").
- * \param mnemonic  Mnemonic toggle; if true, an underscore (_) in the label
- *                  indicates the next character should be used for the
- *                  mnemonic accelerator key (defaults to false).
- */
 Random::Random(Glib::ustring const &label, Glib::ustring const &tooltip,
                unsigned digits,
                Glib::ustring const &suffix,
@@ -73,18 +46,6 @@ Random::Random(Glib::ustring const &label, Glib::ustring const &tooltip,
     addReseedButton();
 }
 
-/**
- * Construct a Random Scalar Widget.
- *
- * \param label     Label.
- * \param adjust    Adjustment to use for the SpinButton.
- * \param digits    Number of decimal digits to display (defaults to 0).
- * \param suffix    Suffix, placed after the widget (defaults to "").
- * \param icon      Icon filename, placed before the label (defaults to "").
- * \param mnemonic  Mnemonic toggle; if true, an underscore (_) in the label
- *                  indicates the next character should be used for the
- *                  mnemonic accelerator key (defaults to true).
- */
 Random::Random(Glib::ustring const &label, Glib::ustring const &tooltip,
                Gtk::Adjustment &adjust,
                unsigned digits,
@@ -97,23 +58,17 @@ Random::Random(Glib::ustring const &label, Glib::ustring const &tooltip,
     addReseedButton();
 }
 
-/** Gets the startseed  */
-long
-Random::getStartSeed() const
+long Random::getStartSeed() const
 {
     return startseed;
 }
 
-/** Sets the startseed number */
-void
-Random::setStartSeed(long newseed)
+void Random::setStartSeed(long newseed)
 {
     startseed = newseed;
 }
 
-/** Add reseed button to the widget */
-void
-Random::addReseedButton()
+void Random::addReseedButton()
 {
     Gtk::Widget*  pIcon = Gtk::manage( sp_icon_get_icon( "randomize", Inkscape::ICON_SIZE_BUTTON) );
     Gtk::Button * pButton = Gtk::manage(new Gtk::Button());
diff --git a/src/ui/widget/random.h b/src/ui/widget/random.h
index 33f416e3f..cb8c223dc 100644
--- a/src/ui/widget/random.h
+++ b/src/ui/widget/random.h
@@ -17,23 +17,62 @@ namespace UI {
 namespace Widget {
 
 /**
- * A labelled text box, with spin buttons and optional icon or suffix, for
- * entering arbitrary number values and generating a random number from it.
+ * A labelled text box, with spin buttons and optional
+ * icon or suffix, for entering arbitrary number values. It adds an extra
+ * number called "startseed", that is not UI edittable, but should be put in SVG.
+ * This does NOT generate a random number, but provides merely the saving of 
+ * the startseed value.
  */
 class Random : public Scalar
 {
 public:
+
+    /**
+     * Construct a Random scalar Widget.
+     *
+     * @param label     Label.
+     * @param suffix    Suffix, placed after the widget (defaults to "").
+     * @param icon      Icon filename, placed before the label (defaults to "").
+     * @param mnemonic  Mnemonic toggle; if true, an underscore (_) in the label
+     *                  indicates the next character should be used for the
+     *                  mnemonic accelerator key (defaults to false).
+     */
     Random(Glib::ustring const &label,
            Glib::ustring const &tooltip,
            Glib::ustring const &suffix = "",
            Glib::ustring const &icon = "",
            bool mnemonic = true);
+
+    /**
+     * Construct a  Random Scalar Widget.
+     *
+     * @param label     Label.
+     * @param digits    Number of decimal digits to display.
+     * @param suffix    Suffix, placed after the widget (defaults to "").
+     * @param icon      Icon filename, placed before the label (defaults to "").
+     * @param mnemonic  Mnemonic toggle; if true, an underscore (_) in the label
+     *                  indicates the next character should be used for the
+     *                  mnemonic accelerator key (defaults to false).
+     */
     Random(Glib::ustring const &label,
            Glib::ustring const &tooltip,
            unsigned digits,
            Glib::ustring const &suffix = "",
            Glib::ustring const &icon = "",
            bool mnemonic = true);
+
+    /**
+     * Construct a Random Scalar Widget.
+     *
+     * @param label     Label.
+     * @param adjust    Adjustment to use for the SpinButton.
+     * @param digits    Number of decimal digits to display (defaults to 0).
+     * @param suffix    Suffix, placed after the widget (defaults to "").
+     * @param icon      Icon filename, placed before the label (defaults to "").
+     * @param mnemonic  Mnemonic toggle; if true, an underscore (_) in the label
+     *                  indicates the next character should be used for the
+     *                  mnemonic accelerator key (defaults to true).
+     */
     Random(Glib::ustring const &label,
            Glib::ustring const &tooltip,
            Gtk::Adjustment &adjust,
@@ -42,7 +81,14 @@ public:
            Glib::ustring const &icon = "",
            bool mnemonic = true);
 
+    /**
+     * Gets the startseed.
+     */
     long getStartSeed() const;
+
+    /**
+     * Sets the startseed number.
+     */
     void setStartSeed(long newseed);
 
     sigc::signal <void> signal_reseeded;
@@ -51,7 +97,12 @@ protected:
     long startseed;
 
 private:
+
+    /**
+     * Add reseed button to the widget.
+     */
     void addReseedButton();
+
     void onReseedButtonClick();
 };
 
diff --git a/src/ui/widget/registered-widget.cpp b/src/ui/widget/registered-widget.cpp
index 3f060f740..f923a7c9c 100644
--- a/src/ui/widget/registered-widget.cpp
+++ b/src/ui/widget/registered-widget.cpp
@@ -1,6 +1,4 @@
-/** \file
- *
- *
+/*
  * Authors:
  *   Johan Engelen <j.b.c.engelen@utwente.nl>
  *   bulia byak <buliabyak@users.sf.net>
@@ -632,13 +630,7 @@ RegisteredVector::setValue(Geom::Point const & p, Geom::Point const & origin)
     _origin = origin;
 }
 
-/**
- * Changes the widgets text to polar coordinates. The SVG output will still be a normal carthesian vector.
- * Careful: when calling getValue(), the return value's X-coord will be the angle, Y-value will be the distance/length. 
- * After changing the coords type (polar/non-polar), the value has to be reset (setValue).
- */
-void
-RegisteredVector::setPolarCoords(bool polar_coords)
+void RegisteredVector::setPolarCoords(bool polar_coords)
 {
     _polar_coords = polar_coords;
     if (polar_coords) {
diff --git a/src/ui/widget/registered-widget.h b/src/ui/widget/registered-widget.h
index a948e1535..df2377464 100644
--- a/src/ui/widget/registered-widget.h
+++ b/src/ui/widget/registered-widget.h
@@ -345,6 +345,12 @@ public:
     // redefine setValue, because transform must be applied
     void setValue(Geom::Point const & p);
     void setValue(Geom::Point const & p, Geom::Point const & origin);
+
+    /**
+     * Changes the widgets text to polar coordinates. The SVG output will still be a normal carthesian vector.
+     * Careful: when calling getValue(), the return value's X-coord will be the angle, Y-value will be the distance/length. 
+     * After changing the coords type (polar/non-polar), the value has to be reset (setValue).
+     */
     void setPolarCoords(bool polar_coords = true);
 
 protected:
diff --git a/src/ui/widget/registry.cpp b/src/ui/widget/registry.cpp
index aa92e6ecb..725e52791 100644
--- a/src/ui/widget/registry.cpp
+++ b/src/ui/widget/registry.cpp
@@ -1,6 +1,4 @@
-/** \file
- *
- *
+/*
  * Authors:
  *   Ralf Stephan <ralf@ark.in-berlin.de> 
  *
diff --git a/src/ui/widget/rendering-options.cpp b/src/ui/widget/rendering-options.cpp
index 1ceaa784e..bbc0a0039 100644
--- a/src/ui/widget/rendering-options.cpp
+++ b/src/ui/widget/rendering-options.cpp
@@ -1,6 +1,4 @@
-/**
- * Rendering options widget.
- *
+/*
  * Author:
  *   Kees Cook <kees@outflux.net>
  *
@@ -23,17 +21,11 @@ namespace Inkscape {
 namespace UI {
 namespace Widget {
 
-void
-RenderingOptions::_toggled()
+void RenderingOptions::_toggled()
 {
     _frame_bitmap.set_sensitive(as_bitmap());
 }
 
-/**
- *    Construct a Rendering Options widget
- *
- */
-
 RenderingOptions::RenderingOptions () :
       Gtk::VBox (),
       _frame_backends ( Glib::ustring(_("Backend")) ),
diff --git a/src/ui/widget/rendering-options.h b/src/ui/widget/rendering-options.h
index 3e2e046d3..241683fe6 100644
--- a/src/ui/widget/rendering-options.h
+++ b/src/ui/widget/rendering-options.h
@@ -24,6 +24,10 @@ namespace Widget {
 class RenderingOptions : public Gtk::VBox
 {
 public:
+
+    /**
+     * Construct a Rendering Options widget.
+     */
     RenderingOptions();
 
     bool as_bitmap();   // should we render as a bitmap?
diff --git a/src/ui/widget/rotateable.cpp b/src/ui/widget/rotateable.cpp
index 6a65d6ab3..c31e6f529 100644
--- a/src/ui/widget/rotateable.cpp
+++ b/src/ui/widget/rotateable.cpp
@@ -1,6 +1,4 @@
-/**
- * widget adjustable by dragging it to rotate away from a zero-change axis.
- *
+/*
  * Authors:
  *   buliabyak@gmail.com
  *
diff --git a/src/ui/widget/scalar-unit.cpp b/src/ui/widget/scalar-unit.cpp
index 47e9b23b2..99ff70846 100644
--- a/src/ui/widget/scalar-unit.cpp
+++ b/src/ui/widget/scalar-unit.cpp
@@ -1,17 +1,4 @@
-/**
- * Scalar Unit Widget - A labelled text box, with spin buttons and
- *        optional icon or suffix, for entering the values of various unit
- *        types.
- *
- * A ScalarUnit is a control for entering, viewing, or manipulating
- * numbers with units.  This differs from ordinary numbers like 2 or
- * 3.14 because the number portion of a scalar *only* has meaning
- * when considered with its unit type.  For instance, 12 m and 12 in
- * have very different actual values, but 1 m and 100 cm have the same
- * value.  The ScalarUnit allows us to abstract the presentation of
- * the scalar to the user from the internal representations used by
- * the program.
- *
+/*
  * Authors:
  *   Bryce Harrington <bryce@bryceharrington.org>
  *   Derek P. Moore <derekm@hackunix.org>
@@ -33,19 +20,6 @@ namespace Inkscape {
 namespace UI {
 namespace Widget {
 
-/**
- * Construct a ScalarUnit
- *
- * \param label      Label.
- * \param unit_type  Unit type (defaults to UNIT_TYPE_LINEAR).
- * \param suffix     Suffix, placed after the widget (defaults to "").
- * \param icon       Icon filename, placed before the label (defaults to "").
- * \param unit_menu  UnitMenu drop down; if not specified, one will be created
- *                   and displayed after the widget (defaults to NULL).
- * \param mnemonic   Mnemonic toggle; if true, an underscore (_) in the label
- *                   indicates the next character should be used for the
- *                   mnemonic accelerator key (defaults to true).
- */
 ScalarUnit::ScalarUnit(Glib::ustring const &label, Glib::ustring const &tooltip,
                        UnitType unit_type,
                        Glib::ustring const &suffix,
@@ -72,18 +46,6 @@ ScalarUnit::ScalarUnit(Glib::ustring const &label, Glib::ustring const &tooltip,
     lastUnits = _unit_menu->getUnitAbbr();
 }
 
-/**
- * Construct a ScalarUnit
- *
- * \param label      Label.
- * \param tooltip    Tooltip text.
- * \param take_unitmenu  Use the unitmenu from this parameter.
- * \param suffix     Suffix, placed after the widget (defaults to "").
- * \param icon       Icon filename, placed before the label (defaults to "").
- * \param mnemonic   Mnemonic toggle; if true, an underscore (_) in the label
- *                   indicates the next character should be used for the
- *                   mnemonic accelerator key (defaults to true).
- */
 ScalarUnit::ScalarUnit(Glib::ustring const &label, Glib::ustring const &tooltip,
                        ScalarUnit &take_unitmenu,
                        Glib::ustring const &suffix,
@@ -104,12 +66,7 @@ ScalarUnit::ScalarUnit(Glib::ustring const &label, Glib::ustring const &tooltip,
 }
 
 
-/**
- * Initializes the scalar based on the settings in _unit_menu.
- * Requires that _unit_menu has already been initialized.
- */
-void
-ScalarUnit::initScalar(double min_value, double max_value)
+void ScalarUnit::initScalar(double min_value, double max_value)
 {
     g_assert(_unit_menu != NULL);
     Scalar::setDigits(_unit_menu->getDefaultDigits());
@@ -118,9 +75,8 @@ ScalarUnit::initScalar(double min_value, double max_value)
     Scalar::setRange(min_value, max_value);
 }
 
-/** Sets the unit for the ScalarUnit widget */
-bool
-ScalarUnit::setUnit(Glib::ustring const &unit) {
+bool ScalarUnit::setUnit(Glib::ustring const &unit)
+{
     g_assert(_unit_menu != NULL);
     // First set the unit
     if (!_unit_menu->setUnit(unit)) {
@@ -130,47 +86,41 @@ ScalarUnit::setUnit(Glib::ustring const &unit) {
     return true;
 }
 
-/** Adds the unit type to the ScalarUnit widget */
-void
-ScalarUnit::setUnitType(UnitType unit_type) {
+void ScalarUnit::setUnitType(UnitType unit_type)
+{
     g_assert(_unit_menu != NULL);
     _unit_menu->setUnitType(unit_type);
     lastUnits = _unit_menu->getUnitAbbr();
 }
 
-/** Resets the unit type for the ScalarUnit widget */
-void
-ScalarUnit::resetUnitType(UnitType unit_type) {
+void ScalarUnit::resetUnitType(UnitType unit_type)
+{
     g_assert(_unit_menu != NULL);
     _unit_menu->resetUnitType(unit_type);
     lastUnits = _unit_menu->getUnitAbbr();
 }
 
-/** Gets the object for the currently selected unit */
-Unit
-ScalarUnit::getUnit() const {
+Unit ScalarUnit::getUnit() const
+{
     g_assert(_unit_menu != NULL);
     return _unit_menu->getUnit();
 }
 
-/** Gets the UnitType ID for the unit */
-UnitType
-ScalarUnit::getUnitType() const {
+UnitType ScalarUnit::getUnitType() const
+{
     g_assert(_unit_menu);
     return _unit_menu->getUnitType();
 }
 
-/** Sets the number and unit system */
-void
-ScalarUnit::setValue(double number, Glib::ustring const &units) {
+void ScalarUnit::setValue(double number, Glib::ustring const &units)
+{
     g_assert(_unit_menu != NULL);
     _unit_menu->setUnit(units);
     Scalar::setValue(number);
 }
 
-/** Convert and sets the number only and keeps the current unit.  */
-void
-ScalarUnit::setValueKeepUnit(double number, Glib::ustring const &units) {
+void ScalarUnit::setValueKeepUnit(double number, Glib::ustring const &units)
+{
     g_assert(_unit_menu != NULL);
     if (units == "") {
         // set the value in the default units
@@ -181,15 +131,13 @@ ScalarUnit::setValueKeepUnit(double number, Glib::ustring const &units) {
     }
 }
 
-/** Sets the number only */
-void
-ScalarUnit::setValue(double number) {
+void ScalarUnit::setValue(double number)
+{
     Scalar::setValue(number);
 }
 
-/** Returns the value in the given unit system */
-double
-ScalarUnit::getValue(Glib::ustring const &unit_name) const {
+double ScalarUnit::getValue(Glib::ustring const &unit_name) const
+{
     g_assert(_unit_menu != NULL);
     if (unit_name == "") {
         // Return the value in the default units
@@ -200,36 +148,29 @@ ScalarUnit::getValue(Glib::ustring const &unit_name) const {
     }
 }
 
-/** Grab focus, and select the text that is in the entry field.
- */
-void
-ScalarUnit::grabFocusAndSelectEntry() {
+void ScalarUnit::grabFocusAndSelectEntry()
+{
     _widget->grab_focus();
     static_cast<SpinButton*>(_widget)->select_region(0, 20);
 }
 
 
-void
-ScalarUnit::setHundredPercent(double number)
+void ScalarUnit::setHundredPercent(double number)
 {
     _hundred_percent = number;
 }
 
-void
-ScalarUnit::setAbsoluteIsIncrement(bool value)
+void ScalarUnit::setAbsoluteIsIncrement(bool value)
 {
     _absolute_is_increment = value;
 }
 
-void
-ScalarUnit::setPercentageIsIncrement(bool value)
+void ScalarUnit::setPercentageIsIncrement(bool value)
 {
     _percentage_is_increment = value;
 }
 
-/** Convert value from % to absolute, using _hundred_percent and *_is_increment flags */
-double
-ScalarUnit::PercentageToAbsolute(double value)
+double ScalarUnit::PercentageToAbsolute(double value)
 {
     // convert from percent to absolute
     double convertedVal = 0;
@@ -243,9 +184,7 @@ ScalarUnit::PercentageToAbsolute(double value)
     return convertedVal;
 }
 
-/** Convert value from absolute to %, using _hundred_percent and *_is_increment flags */
-double
-ScalarUnit::AbsoluteToPercentage(double value)
+double ScalarUnit::AbsoluteToPercentage(double value)
 {
     double convertedVal = 0;
     // convert from absolute to percent
@@ -266,27 +205,21 @@ ScalarUnit::AbsoluteToPercentage(double value)
     return convertedVal;
 }
 
-/** Assuming the current unit is absolute, get the corresponding % value */
-double
-ScalarUnit::getAsPercentage()
+double ScalarUnit::getAsPercentage()
 {
     double convertedVal = AbsoluteToPercentage(Scalar::getValue());
     return convertedVal;
 }
 
 
-/** Assuming the current unit is absolute, set the value corresponding to a given % */
-void 
-ScalarUnit::setFromPercentage(double value)
+void  ScalarUnit::setFromPercentage(double value)
 {
     double absolute = PercentageToAbsolute(value);
     Scalar::setValue(absolute);
 }
 
 
-/** Signal handler for updating the value and suffix label when unit is changed */
-void
-ScalarUnit::on_unit_changed()
+void ScalarUnit::on_unit_changed()
 {
     g_assert(_unit_menu != NULL);
 
diff --git a/src/ui/widget/scalar-unit.h b/src/ui/widget/scalar-unit.h
index 05a7b95f8..4f22f438c 100644
--- a/src/ui/widget/scalar-unit.h
+++ b/src/ui/widget/scalar-unit.h
@@ -22,47 +22,142 @@ namespace Widget {
 /**
  * A labelled text box, with spin buttons and optional icon or suffix, for
  * entering the values of various unit types.
+ *
+ * A ScalarUnit is a control for entering, viewing, or manipulating
+ * numbers with units.  This differs from ordinary numbers like 2 or
+ * 3.14 because the number portion of a scalar *only* has meaning
+ * when considered with its unit type.  For instance, 12 m and 12 in
+ * have very different actual values, but 1 m and 100 cm have the same
+ * value.  The ScalarUnit allows us to abstract the presentation of
+ * the scalar to the user from the internal representations used by
+ * the program.
  */
 class ScalarUnit : public Scalar
 {
 public:
+    /**
+     * Construct a ScalarUnit.
+     *
+     * @param label      Label.
+     * @param unit_type  Unit type (defaults to UNIT_TYPE_LINEAR).
+     * @param suffix     Suffix, placed after the widget (defaults to "").
+     * @param icon       Icon filename, placed before the label (defaults to "").
+     * @param unit_menu  UnitMenu drop down; if not specified, one will be created
+     *                   and displayed after the widget (defaults to NULL).
+     * @param mnemonic   Mnemonic toggle; if true, an underscore (_) in the label
+     *                   indicates the next character should be used for the
+     *                   mnemonic accelerator key (defaults to true).
+     */
     ScalarUnit(Glib::ustring const &label, Glib::ustring const &tooltip,
                UnitType unit_type = UNIT_TYPE_LINEAR,
                Glib::ustring const &suffix = "",
                Glib::ustring const &icon = "",
                UnitMenu *unit_menu = NULL,
                bool mnemonic = true);
+
+    /**
+     * Construct a ScalarUnit.
+     *
+     * @param label      Label.
+     * @param tooltip    Tooltip text.
+     * @param take_unitmenu  Use the unitmenu from this parameter.
+     * @param suffix     Suffix, placed after the widget (defaults to "").
+     * @param icon       Icon filename, placed before the label (defaults to "").
+     * @param mnemonic   Mnemonic toggle; if true, an underscore (_) in the label
+     *                   indicates the next character should be used for the
+     *                   mnemonic accelerator key (defaults to true).
+     */
     ScalarUnit(Glib::ustring const &label, Glib::ustring const &tooltip,
                ScalarUnit &take_unitmenu,
                Glib::ustring const &suffix = "",
                Glib::ustring const &icon = "",
                bool mnemonic = true);
 
+    /**
+     * Initializes the scalar based on the settings in _unit_menu.
+     * Requires that _unit_menu has already been initialized.
+     */
     void      initScalar(double min_value, double max_value);
 
+    /**
+     * Gets the object for the currently selected unit.
+     */
     Unit      getUnit() const;
+
+    /**
+     * Gets the UnitType ID for the unit.
+     */
     UnitType  getUnitType() const;
+
+    /**
+     * Returns the value in the given unit system.
+     */
     double    getValue(Glib::ustring const &units) const;
 
+    /**
+     * Sets the unit for the ScalarUnit widget.
+     */
     bool      setUnit(Glib::ustring const &units);
+
+    /**
+     * Adds the unit type to the ScalarUnit widget.
+     */
     void      setUnitType(UnitType unit_type);
+
+    /**
+     * Resets the unit type for the ScalarUnit widget.
+     */
     void      resetUnitType(UnitType unit_type);
+
+    /**
+     * Sets the number and unit system.
+     */
     void      setValue(double number, Glib::ustring const &units);
+
+    /**
+     * Convert and sets the number only and keeps the current unit.
+     */
     void      setValueKeepUnit(double number, Glib::ustring const &units);
+
+    /**
+     * Sets the number only.
+     */
     void      setValue(double number);
 
+    /**
+     * Grab focus, and select the text that is in the entry field.
+     */
     void      grabFocusAndSelectEntry();
 
     void      setHundredPercent(double number);
+
     void      setAbsoluteIsIncrement(bool value);
+
     void      setPercentageIsIncrement(bool value);
 
+    /**
+     * Convert value from % to absolute, using _hundred_percent and *_is_increment flags.
+     */
     double PercentageToAbsolute(double value);
+
+    /**
+     * Convert value from absolute to %, using _hundred_percent and *_is_increment flags.
+     */
     double AbsoluteToPercentage(double value);
 
+    /**
+     * Assuming the current unit is absolute, get the corresponding % value.
+     */
     double getAsPercentage();
+
+    /**
+     * Assuming the current unit is absolute, set the value corresponding to a given %.
+     */
     void setFromPercentage(double value);
 
+    /**
+     * Signal handler for updating the value and suffix label when unit is changed.
+     */
     void on_unit_changed();
 
 protected:
diff --git a/src/ui/widget/scalar.cpp b/src/ui/widget/scalar.cpp
index 4237d9db9..220498561 100644
--- a/src/ui/widget/scalar.cpp
+++ b/src/ui/widget/scalar.cpp
@@ -1,7 +1,4 @@
-/**
- * Scalar Widget - A labelled text box, with spin buttons and optional
- *        icon or suffix, for entering arbitrary number values.
- *
+/*
  * Authors:
  *   Carl Hetherington <inkscape@carlh.net>
  *   Derek P. Moore <derekm@hackunix.org>
@@ -24,16 +21,6 @@ namespace Inkscape {
 namespace UI {
 namespace Widget {
 
-/**
- * Construct a Scalar Widget.
- *
- * \param label     Label.
- * \param suffix    Suffix, placed after the widget (defaults to "").
- * \param icon      Icon filename, placed before the label (defaults to "").
- * \param mnemonic  Mnemonic toggle; if true, an underscore (_) in the label
- *                  indicates the next character should be used for the
- *                  mnemonic accelerator key (defaults to false).
- */
 Scalar::Scalar(Glib::ustring const &label, Glib::ustring const &tooltip,
                Glib::ustring const &suffix,
                Glib::ustring const &icon,
@@ -43,17 +30,6 @@ Scalar::Scalar(Glib::ustring const &label, Glib::ustring const &tooltip,
 {
 }
 
-/**
- * Construct a Scalar Widget.
- *
- * \param label     Label.
- * \param digits    Number of decimal digits to display.
- * \param suffix    Suffix, placed after the widget (defaults to "").
- * \param icon      Icon filename, placed before the label (defaults to "").
- * \param mnemonic  Mnemonic toggle; if true, an underscore (_) in the label
- *                  indicates the next character should be used for the
- *                  mnemonic accelerator key (defaults to false).
- */
 Scalar::Scalar(Glib::ustring const &label, Glib::ustring const &tooltip,
                unsigned digits,
                Glib::ustring const &suffix,
@@ -64,18 +40,6 @@ Scalar::Scalar(Glib::ustring const &label, Glib::ustring const &tooltip,
 {
 }
 
-/**
- * Construct a Scalar Widget.
- *
- * \param label     Label.
- * \param adjust    Adjustment to use for the SpinButton.
- * \param digits    Number of decimal digits to display (defaults to 0).
- * \param suffix    Suffix, placed after the widget (defaults to "").
- * \param icon      Icon filename, placed before the label (defaults to "").
- * \param mnemonic  Mnemonic toggle; if true, an underscore (_) in the label
- *                  indicates the next character should be used for the
- *                  mnemonic accelerator key (defaults to true).
- */
 Scalar::Scalar(Glib::ustring const &label, Glib::ustring const &tooltip,
                Gtk::Adjustment &adjust,
                unsigned digits,
@@ -87,17 +51,13 @@ Scalar::Scalar(Glib::ustring const &label, Glib::ustring const &tooltip,
 {
 }
 
-/** Fetches the precision of the spin buton */
-unsigned
-Scalar::getDigits() const
+unsigned Scalar::getDigits() const
 {
     g_assert(_widget != NULL);
     return static_cast<SpinButton*>(_widget)->get_digits();
 }
 
-/** Gets the current step ingrement used by the spin button */
-double
-Scalar::getStep() const
+double Scalar::getStep() const
 {
     g_assert(_widget != NULL);
     double step, page;
@@ -105,9 +65,7 @@ Scalar::getStep() const
     return step;
 }
 
-/** Gets the current page increment used by the spin button */
-double
-Scalar::getPage() const
+double Scalar::getPage() const
 {
     g_assert(_widget != NULL);
     double step, page;
@@ -115,9 +73,7 @@ Scalar::getPage() const
     return page;
 }
 
-/** Gets the minimum range value allowed for the spin button */
-double
-Scalar::getRangeMin() const
+double Scalar::getRangeMin() const
 {
     g_assert(_widget != NULL);
     double min, max;
@@ -125,9 +81,7 @@ Scalar::getRangeMin() const
     return min;
 }
 
-/** Gets the maximum range value allowed for the spin button */
-double
-Scalar::getRangeMax() const
+double Scalar::getRangeMax() const
 {
     g_assert(_widget != NULL);
     double min, max;
@@ -135,70 +89,53 @@ Scalar::getRangeMax() const
     return max;
 }
 
-/** Get the value in the spin_button . */
-double
-Scalar::getValue() const
+double Scalar::getValue() const
 {
     g_assert(_widget != NULL);
     return static_cast<SpinButton*>(_widget)->get_value();
 }
 
-/** Get the value spin_button represented as an integer. */
-int
-Scalar::getValueAsInt() const
+int Scalar::getValueAsInt() const
 {
     g_assert(_widget != NULL);
     return static_cast<SpinButton*>(_widget)->get_value_as_int();
 }
 
 
-/** Sets the precision to be displayed by the spin button */
-void
-Scalar::setDigits(unsigned digits)
+void Scalar::setDigits(unsigned digits)
 {
     g_assert(_widget != NULL);
     static_cast<SpinButton*>(_widget)->set_digits(digits);
 }
 
-/** Sets the step and page increments for the spin button
- * @todo Remove the second parameter - deprecated
- */
-void
-Scalar::setIncrements(double step, double /*page*/)
+void Scalar::setIncrements(double step, double /*page*/)
 {
     g_assert(_widget != NULL);
     static_cast<SpinButton*>(_widget)->set_increments(step, 0);
 }
 
-/** Sets the minimum and maximum range allowed for the spin button */
-void
-Scalar::setRange(double min, double max)
+void Scalar::setRange(double min, double max)
 {
     g_assert(_widget != NULL);
     static_cast<SpinButton*>(_widget)->set_range(min, max);
 }
 
-/** Sets the value of the spin button */
-void
-Scalar::setValue(double value)
+void Scalar::setValue(double value)
 {
     g_assert(_widget != NULL);
     setProgrammatically = true; // callback is supposed to reset back, if it cares
     static_cast<SpinButton*>(_widget)->set_value(value);
 }
 
-/** Manually forces an update of the spin button */
-void
-Scalar::update() {
+void Scalar::update()
+{
     g_assert(_widget != NULL);
     static_cast<SpinButton*>(_widget)->update();
 }
 
 
 
-/** Signal raised when the spin button's value changes */
-Glib::SignalProxy0<void>
-Scalar::signal_value_changed()
+Glib::SignalProxy0<void> Scalar::signal_value_changed()
 {
     return static_cast<SpinButton*>(_widget)->signal_value_changed();
 }
diff --git a/src/ui/widget/scalar.h b/src/ui/widget/scalar.h
index 66bd07ddb..c73bcc62a 100644
--- a/src/ui/widget/scalar.h
+++ b/src/ui/widget/scalar.h
@@ -25,17 +25,52 @@ namespace Widget {
 class Scalar : public Labelled
 {
 public:
+    /**
+     * Construct a Scalar Widget.
+     *
+     * @param label     Label.
+     * @param suffix    Suffix, placed after the widget (defaults to "").
+     * @param icon      Icon filename, placed before the label (defaults to "").
+     * @param mnemonic  Mnemonic toggle; if true, an underscore (_) in the label
+     *                  indicates the next character should be used for the
+     *                  mnemonic accelerator key (defaults to false).
+     */
     Scalar(Glib::ustring const &label,
            Glib::ustring const &tooltip,
            Glib::ustring const &suffix = "",
            Glib::ustring const &icon = "",
            bool mnemonic = true);
+
+    /**
+     * Construct a Scalar Widget.
+     *
+     * @param label     Label.
+     * @param digits    Number of decimal digits to display.
+     * @param suffix    Suffix, placed after the widget (defaults to "").
+     * @param icon      Icon filename, placed before the label (defaults to "").
+     * @param mnemonic  Mnemonic toggle; if true, an underscore (_) in the label
+     *                  indicates the next character should be used for the
+     *                  mnemonic accelerator key (defaults to false).
+     */
     Scalar(Glib::ustring const &label,
            Glib::ustring const &tooltip,
            unsigned digits,
            Glib::ustring const &suffix = "",
            Glib::ustring const &icon = "",
            bool mnemonic = true);
+
+    /**
+     * Construct a Scalar Widget.
+     *
+     * @param label     Label.
+     * @param adjust    Adjustment to use for the SpinButton.
+     * @param digits    Number of decimal digits to display (defaults to 0).
+     * @param suffix    Suffix, placed after the widget (defaults to "").
+     * @param icon      Icon filename, placed before the label (defaults to "").
+     * @param mnemonic  Mnemonic toggle; if true, an underscore (_) in the label
+     *                  indicates the next character should be used for the
+     *                  mnemonic accelerator key (defaults to true).
+     */
     Scalar(Glib::ustring const &label,
            Glib::ustring const &tooltip,
            Gtk::Adjustment &adjust,
@@ -44,26 +79,79 @@ public:
            Glib::ustring const &icon = "",
            bool mnemonic = true);
 
+    /**
+     * Fetches the precision of the spin buton.
+     */
     unsigned getDigits() const;
+
+    /**
+     * Gets the current step ingrement used by the spin button.
+     */
     double  getStep() const;
+
+    /**
+     * Gets the current page increment used by the spin button.
+     */
     double  getPage() const;
+
+    /**
+     * Gets the minimum range value allowed for the spin button.
+     */
     double  getRangeMin() const;
+
+    /**
+     * Gets the maximum range value allowed for the spin button.
+     */
     double  getRangeMax() const;
+
     bool    getSnapToTicks() const;
+
+    /**
+     * Get the value in the spin_button.
+     */
     double  getValue() const;
+
+    /**
+     * Get the value spin_button represented as an integer.
+     */
     int     getValueAsInt() const;
 
+    /**
+     * Sets the precision to be displayed by the spin button.
+     */
     void    setDigits(unsigned digits);
+
+    /**
+     * Sets the step and page increments for the spin button.
+     * @todo Remove the second parameter - deprecated
+     */
     void    setIncrements(double step, double page);
+
+    /**
+     * Sets the minimum and maximum range allowed for the spin button.
+     */
     void    setRange(double min, double max);
+
+    /**
+     * Sets the value of the spin button.
+     */
     void    setValue(double value);
 
+    /**
+     * Manually forces an update of the spin button.
+     */
     void    update();
 
+    /**
+     * Signal raised when the spin button's value changes.
+     */
     Glib::SignalProxy0<void> signal_value_changed();
 
-    bool setProgrammatically; // true if the value was set by setValue, not changed by the user; 
-                                    // if a callback checks it, it must reset it back to false
+    /**
+     * true if the value was set by setValue, not changed by the user;
+     * if a callback checks it, it must reset it back to false.
+     */
+    bool setProgrammatically;
 };
 
 } // namespace Widget
diff --git a/src/ui/widget/selected-style.cpp b/src/ui/widget/selected-style.cpp
index 51c3af4dd..b6722f4cf 100644
--- a/src/ui/widget/selected-style.cpp
+++ b/src/ui/widget/selected-style.cpp
@@ -1,6 +1,4 @@
-/**
- * Selected style indicator (fill, stroke, opacity).
- *
+/*
  * Author:
  *   buliabyak@gmail.com
  *   Abhishek Sharma
diff --git a/src/ui/widget/spin-slider.cpp b/src/ui/widget/spin-slider.cpp
index 4a3b0dd77..da2db991e 100644
--- a/src/ui/widget/spin-slider.cpp
+++ b/src/ui/widget/spin-slider.cpp
@@ -1,6 +1,4 @@
-/**
- * Groups an HScale and a SpinButton together using the same Adjustment.
- *
+/*
  * Author:
  *   Nicholas Bishop <nicholasbishop@gmail.com>
  *   Felipe C. da S. Sanches <juca@members.fsf.org>
diff --git a/src/ui/widget/spinbutton.cpp b/src/ui/widget/spinbutton.cpp
index 78b00bebc..60b7856f6 100644
--- a/src/ui/widget/spinbutton.cpp
+++ b/src/ui/widget/spinbutton.cpp
@@ -1,6 +1,3 @@
-/**
- * SpinButton widget, that allows entry of both '.' and ',' for the decimal, even when in numeric mode.
- */
 /*
  * Author:
  *   Johan B. C. Engelen
@@ -32,15 +29,7 @@ SpinButton::connect_signals() {
     signal_key_press_event().connect(sigc::mem_fun(*this, &SpinButton::on_my_key_press_event));
 };
 
-/**
- * This callback function should try to convert the entered text to a number and write it to newvalue.
- * It calls a method to evaluate the (potential) mathematical expression.
- *
- * @retval false No conversion done, continue with default handler.
- * @retval true  Conversion successful, don't call default handler. 
- */
-int
-SpinButton::on_input(double* newvalue)
+int SpinButton::on_input(double* newvalue)
 {
     try {
         Inkscape::Util::GimpEevlQuantity result;
@@ -66,23 +55,13 @@ SpinButton::on_input(double* newvalue)
     return true;
 }
 
-/** When focus is obtained, save the value to enable undo later.
- * @retval false continue with default handler.
- * @retval true  don't call default handler. 
-*/
-bool
-SpinButton::on_my_focus_in_event(GdkEventFocus* /*event*/)
+bool SpinButton::on_my_focus_in_event(GdkEventFocus* /*event*/)
 {
     on_focus_in_value = get_value();
     return false; // do not consume the event
 }
 
-/** Handle specific keypress events, like Ctrl+Z
- * @retval false continue with default handler.
- * @retval true  don't call default handler. 
-*/
-bool
-SpinButton::on_my_key_press_event(GdkEventKey* event)
+bool SpinButton::on_my_key_press_event(GdkEventKey* event)
 {
     switch (get_group0_keyval (event)) {
     case GDK_Escape:
@@ -103,11 +82,7 @@ SpinButton::on_my_key_press_event(GdkEventKey* event)
     return false; // do not consume the event
 }
 
-/**
- * Undo the editing, by resetting the value upon when the spinbutton got focus.
- */
-void
-SpinButton::undo()
+void SpinButton::undo()
 {
     set_value(on_focus_in_value);
 }
diff --git a/src/ui/widget/spinbutton.h b/src/ui/widget/spinbutton.h
index df913553d..b7764d979 100644
--- a/src/ui/widget/spinbutton.h
+++ b/src/ui/widget/spinbutton.h
@@ -1,6 +1,3 @@
-/**
- * \brief SpinButton widget, that allows entry of both '.' and ',' for the decimal, even when in numeric mode.
- */
 /*
  * Author:
  *   Johan B. C. Engelen
@@ -22,7 +19,8 @@ namespace Widget {
 class UnitMenu;
 
 /**
- * SpinButton widget, that allows entry of simple math expressions (also units, when linked with UnitMenu).
+ * SpinButton widget, that allows entry of simple math expressions (also units, when linked with UnitMenu),
+ * and allows entry of both '.' and ',' for the decimal, even when in numeric mode.
  *
  * Calling "set_numeric()" effectively disables the expression parsing. If no unit menu is linked, all unitlike characters are ignored.
  */
@@ -50,10 +48,35 @@ protected:
   UnitMenu *_unit_menu; /// Linked unit menu for unit conversion in entered expressions.
 
   void connect_signals();
-  int on_input(double* newvalue);
-  bool on_my_focus_in_event(GdkEventFocus* event);
-  bool on_my_key_press_event(GdkEventKey* event);
-  void undo();
+
+    /**
+     * This callback function should try to convert the entered text to a number and write it to newvalue.
+     * It calls a method to evaluate the (potential) mathematical expression.
+     *
+     * @retval false No conversion done, continue with default handler.
+     * @retval true  Conversion successful, don't call default handler. 
+     */
+    int on_input(double* newvalue);
+
+    /**
+     * When focus is obtained, save the value to enable undo later.
+     * @retval false continue with default handler.
+     * @retval true  don't call default handler. 
+     */
+    bool on_my_focus_in_event(GdkEventFocus* event);
+
+    /**
+     * Handle specific keypress events, like Ctrl+Z.
+     *
+     * @retval false continue with default handler.
+     * @retval true  don't call default handler. 
+     */
+    bool on_my_key_press_event(GdkEventKey* event);
+
+    /**
+     * Undo the editing, by resetting the value upon when the spinbutton got focus.
+     */
+    void undo();
 
   double on_focus_in_value;
 
diff --git a/src/ui/widget/style-subject.cpp b/src/ui/widget/style-subject.cpp
index 4a1b83175..d9bf7e2aa 100644
--- a/src/ui/widget/style-subject.cpp
+++ b/src/ui/widget/style-subject.cpp
@@ -1,6 +1,4 @@
-/**
- * Abstraction for different style widget operands.
- *
+/*
  * Copyright (C) 2007 MenTaLguY <mental@rydia.net>
  *   Abhishek Sharma
  *
diff --git a/src/ui/widget/svg-canvas.cpp b/src/ui/widget/svg-canvas.cpp
index f0eb24a10..d3d9f70f2 100644
--- a/src/ui/widget/svg-canvas.cpp
+++ b/src/ui/widget/svg-canvas.cpp
@@ -1,6 +1,4 @@
-/** \file
- * Gtkmm facade/wrapper around SPCanvas.
- *
+/*
  * Authors:
  *   Ralf Stephan <ralf@ark.in-berlin.de>
  *
diff --git a/src/ui/widget/text.cpp b/src/ui/widget/text.cpp
index a5540e428..b79bea067 100644
--- a/src/ui/widget/text.cpp
+++ b/src/ui/widget/text.cpp
@@ -1,7 +1,4 @@
-/**
- * Text Widget - A labelled text box, with spin buttons and optional
- *        icon or suffix, for entering arbitrary number values.
- *
+/*
  * Authors:
  *   Carl Hetherington <inkscape@carlh.net>
  *   Maximilian Albert <maximilian.albert@gmail.com>
@@ -22,16 +19,6 @@ namespace Inkscape {
 namespace UI {
 namespace Widget {
 
-/**
- * Construct a Text Widget.
- *
- * \param label     Label.
- * \param suffix    Suffix, placed after the widget (defaults to "").
- * \param icon      Icon filename, placed before the label (defaults to "").
- * \param mnemonic  Mnemonic toggle; if true, an underscore (_) in the label
- *                  indicates the next character should be used for the
- *                  mnemonic accelerator key (defaults to false).
- */
 Text::Text(Glib::ustring const &label, Glib::ustring const &tooltip,
                Glib::ustring const &suffix,
                Glib::ustring const &icon,
@@ -41,26 +28,20 @@ Text::Text(Glib::ustring const &label, Glib::ustring const &tooltip,
 {
 }
 
-/** Get the text in the entry */
-const char *
-Text::getText() const
+const char *Text::getText() const
 {
     g_assert(_widget != NULL);
     return static_cast<Gtk::Entry*>(_widget)->get_text().c_str();
 }
 
-/** Sets the text of the text entry */
-void
-Text::setText(const char* text)
+void Text::setText(const char* text)
 {
     g_assert(_widget != NULL);
     setProgrammatically = true; // callback is supposed to reset back, if it cares
     static_cast<Gtk::Entry*>(_widget)->set_text(text); // FIXME: set correctly
 }
 
-/** Signal raised when the spin button's value changes */
-Glib::SignalProxy0<void>
-Text::signal_activate()
+Glib::SignalProxy0<void> Text::signal_activate()
 {
     return static_cast<Gtk::Entry*>(_widget)->signal_activate();
 }
diff --git a/src/ui/widget/text.h b/src/ui/widget/text.h
index bccaefa2e..0f6efd01f 100644
--- a/src/ui/widget/text.h
+++ b/src/ui/widget/text.h
@@ -26,18 +26,38 @@ namespace Widget {
 class Text : public Labelled
 {
 public:
+
+    /**
+     * Construct a Text Widget.
+     *
+     * @param label     Label.
+     * @param suffix    Suffix, placed after the widget (defaults to "").
+     * @param icon      Icon filename, placed before the label (defaults to "").
+     * @param mnemonic  Mnemonic toggle; if true, an underscore (_) in the label
+     *                  indicates the next character should be used for the
+     *                  mnemonic accelerator key (defaults to false).
+     */
     Text(Glib::ustring const &label,
 	 Glib::ustring const &tooltip,
 	 Glib::ustring const &suffix = "",
 	 Glib::ustring const &icon = "",
 	 bool mnemonic = true);
 
+    /**
+     * Get the text in the entry.
+     */
     const char* getText() const;
 
+    /**
+     * Sets the text of the text entry.
+     */
     void setText(const char* text);
 
     void update();
 
+    /**
+     * Signal raised when the spin button's value changes.
+     */
     Glib::SignalProxy0<void> signal_activate();
 
     bool setProgrammatically; // true if the value was set by setValue, not changed by the user;
diff --git a/src/ui/widget/tolerance-slider.cpp b/src/ui/widget/tolerance-slider.cpp
index 51e0a262f..40f58f0ae 100644
--- a/src/ui/widget/tolerance-slider.cpp
+++ b/src/ui/widget/tolerance-slider.cpp
@@ -1,7 +1,4 @@
-/** \file
- *
- Implementation of tolerance slider widget.
- *
+/*
  * Authors:
  *   Ralf Stephan <ralf@ark.in-berlin.de> 
  *   Abhishek Sharma
diff --git a/src/ui/widget/tolerance-slider.h b/src/ui/widget/tolerance-slider.h
index 22c04d361..0a9663bc3 100644
--- a/src/ui/widget/tolerance-slider.h
+++ b/src/ui/widget/tolerance-slider.h
@@ -1,8 +1,3 @@
-/** \file
- * \brief 
- *
- * This widget is part of the Document properties dialog.
- */
 /*
  * Authors:
  *   Ralf Stephan <ralf@ark.in-berlin.de>
@@ -27,6 +22,10 @@ namespace Widget {
 
 class Registry;
 
+/**
+ * Implementation of tolerance slider widget.
+ * This widget is part of the Document properties dialog.
+ */
 class ToleranceSlider {
 public:
     ToleranceSlider();
diff --git a/src/ui/widget/toolbox.cpp b/src/ui/widget/toolbox.cpp
index 41a13f4e9..99891fc44 100644
--- a/src/ui/widget/toolbox.cpp
+++ b/src/ui/widget/toolbox.cpp
@@ -1,6 +1,4 @@
-/**
- * Toolbox Widget - A detachable toolbar for buttons and other widgets.
- *
+/*
  * Author:
  *   Derek P. Moore <derekm@hackunix.org>
  *
diff --git a/src/ui/widget/unit-menu.cpp b/src/ui/widget/unit-menu.cpp
index bb0b65576..085783481 100644
--- a/src/ui/widget/unit-menu.cpp
+++ b/src/ui/widget/unit-menu.cpp
@@ -1,6 +1,4 @@
-/**
- * Unit Menu Widget - A drop down menu for choosing unit types.
- *
+/*
  * Author:
  *   Bryce Harrington <bryce@bryceharrington.org>
  *
@@ -21,10 +19,6 @@ namespace Inkscape {
 namespace UI {
 namespace Widget {
 
-/**
- *    Construct a UnitMenu
- *
- */
 UnitMenu::UnitMenu() : _type(UNIT_TYPE_NONE)
 {
     set_active(0);
@@ -33,14 +27,9 @@ UnitMenu::UnitMenu() : _type(UNIT_TYPE_NONE)
 UnitMenu::~UnitMenu() {
 }
 
-/** Adds the unit type to the widget.  This extracts the corresponding
-    units from the unit map matching the given type, and appends them
-    to the dropdown widget.  It causes the primary unit for the given
-    unit_type to be selected.  */
-bool
-UnitMenu::setUnitType(UnitType unit_type) 
+bool UnitMenu::setUnitType(UnitType unit_type) 
 {
-    /* Expand the unit widget with unit entries from the unit table */
+    // Expand the unit widget with unit entries from the unit table
     UnitTable::UnitMap m = _unit_table.units(unit_type);
     UnitTable::UnitMap::iterator iter = m.begin();
     while(iter != m.end()) {
@@ -54,31 +43,21 @@ UnitMenu::setUnitType(UnitType unit_type)
     return true;
 }
 
-/** Removes all unit entries, then adds the unit type to the widget.
-    This extracts the corresponding
-    units from the unit map matching the given type, and appends them
-    to the dropdown widget.  It causes the primary unit for the given
-    unit_type to be selected.  */
-bool
-UnitMenu::resetUnitType(UnitType unit_type) 
+bool UnitMenu::resetUnitType(UnitType unit_type) 
 {
     clear_text();
 
     return setUnitType(unit_type);
 }
 
-/** Adds a unit, possibly user-defined, to the menu. */
-void
-UnitMenu::addUnit(Unit const& u)
+void UnitMenu::addUnit(Unit const& u)
 {
     _unit_table.addUnit(u, false);
     append_text(u.abbr);
 }
 
-/** Returns the Unit object corresponding to the current selection
-    in the dropdown widget */
-Unit
-UnitMenu::getUnit() const {
+Unit UnitMenu::getUnit() const
+{
     if (get_active_text() == "") {
         g_assert(_type != UNIT_TYPE_NONE);
         return _unit_table.getUnit(_unit_table.primary(_type));
@@ -86,11 +65,8 @@ UnitMenu::getUnit() const {
     return _unit_table.getUnit(get_active_text());
 }
 
-/** Sets the dropdown widget to the given unit abbreviation. 
-    Returns true if the unit was selectable, false if not 
-    (i.e., if the unit was not present in the widget) */
-bool
-UnitMenu::setUnit(Glib::ustring const & unit) {
+bool UnitMenu::setUnit(Glib::ustring const & unit)
+{
     // TODO:  Determine if 'unit' is available in the dropdown.
     //        If not, return false
 
@@ -98,63 +74,41 @@ UnitMenu::setUnit(Glib::ustring const & unit) {
     return true;
 }
 
-/** Returns the abbreviated unit name of the selected unit */
-Glib::ustring
-UnitMenu::getUnitAbbr() const {
+Glib::ustring UnitMenu::getUnitAbbr() const
+{
     if (get_active_text() == "") {
         return "";
     }
     return getUnit().abbr;
 }
 
-/** Returns the UnitType of the selected unit */
-UnitType
-UnitMenu::getUnitType() const {
+UnitType UnitMenu::getUnitType() const
+{
     return getUnit().type;
 }
 
-/** Returns the unit factor for the selected unit */
-double 
-UnitMenu::getUnitFactor() const
+double  UnitMenu::getUnitFactor() const
 {
     return getUnit().factor;
 }
 
-/** Returns the recommended number of digits for displaying
- *  numbers of this unit type.  
- */
-int
-UnitMenu::getDefaultDigits() const
+int UnitMenu::getDefaultDigits() const
 {
     return getUnit().defaultDigits();
 }
 
-/** Returns the recommended step size in spin buttons
- *  displaying units of this type
- */
-double
-UnitMenu::getDefaultStep() const
+double UnitMenu::getDefaultStep() const
 { 
     int factor_digits = -1*int(log10(getUnit().factor));
     return pow(10.0, factor_digits);
 }
 
-/** Returns the recommended page size (when hitting pgup/pgdn)
- *  in spin buttons displaying units of this type
- */
-double
-UnitMenu::getDefaultPage() const
+double UnitMenu::getDefaultPage() const
 {
     return 10 * getDefaultStep();
 }
 
-/**
- *  Returns the conversion factor required to convert values
- *  of the currently selected unit into units of type
- *  new_unit_abbr.
- */
-double
-UnitMenu::getConversion(Glib::ustring const &new_unit_abbr, Glib::ustring const &old_unit_abbr) const
+double UnitMenu::getConversion(Glib::ustring const &new_unit_abbr, Glib::ustring const &old_unit_abbr) const
 {
     double old_factor = getUnit().factor;
     if (old_unit_abbr != "no_unit")
@@ -171,18 +125,13 @@ UnitMenu::getConversion(Glib::ustring const &new_unit_abbr, Glib::ustring const
     return old_factor / new_unit.factor;
 }
 
-/** Returns true if the selected unit is not dimensionless 
- *  (false for %, true for px, pt, cm, etc) 
- */
-bool
-UnitMenu::isAbsolute() const {
+bool UnitMenu::isAbsolute() const
+{
     return getUnitType() != UNIT_TYPE_DIMENSIONLESS;
 }
 
-/** Returns true if the selected unit is radial (deg or rad)
- */
-bool
-UnitMenu::isRadial() const {
+bool UnitMenu::isRadial() const
+{
     return getUnitType() == UNIT_TYPE_RADIAL;
 }
 
diff --git a/src/ui/widget/unit-menu.h b/src/ui/widget/unit-menu.h
index cb11bbb30..61e93bd65 100644
--- a/src/ui/widget/unit-menu.h
+++ b/src/ui/widget/unit-menu.h
@@ -25,27 +25,98 @@ namespace Widget {
 class UnitMenu : public ComboText
 {
 public:
+
+    /**
+     *    Construct a UnitMenu
+     */
     UnitMenu();
+
     virtual ~UnitMenu();
 
+    /**
+     * Adds the unit type to the widget.  This extracts the corresponding
+     * units from the unit map matching the given type, and appends them
+     * to the dropdown widget.  It causes the primary unit for the given
+     * unit_type to be selected.
+     */
     bool          setUnitType(UnitType unit_type);
+
+    /**
+     * Removes all unit entries, then adds the unit type to the widget.
+     * This extracts the corresponding
+     * units from the unit map matching the given type, and appends them
+     * to the dropdown widget.  It causes the primary unit for the given
+     * unit_type to be selected.
+     */
     bool          resetUnitType(UnitType unit_type);
+
+    /**
+     * Adds a unit, possibly user-defined, to the menu.
+     */
     void          addUnit(Unit const& u);
 
+    /**
+     * Sets the dropdown widget to the given unit abbreviation. 
+     * Returns true if the unit was selectable, false if not 
+     * (i.e., if the unit was not present in the widget).
+     */
     bool          setUnit(Glib::ustring const &unit);
 
+    /**
+     * Returns the Unit object corresponding to the current selection
+     * in the dropdown widget.
+     */
     Unit          getUnit() const;
+
+    /**
+     * Returns the abbreviated unit name of the selected unit.
+     */
     Glib::ustring getUnitAbbr() const;
+
+    /**
+     * Returns the UnitType of the selected unit.
+     */
     UnitType      getUnitType() const;
+
+    /**
+     * Returns the unit factor for the selected unit.
+     */
     double        getUnitFactor() const;
 
+    /**
+     * Returns the recommended number of digits for displaying
+     *  numbers of this unit type.  
+     */
     int           getDefaultDigits() const;
+
+    /**
+     * Returns the recommended step size in spin buttons
+     *  displaying units of this type.
+     */
     double        getDefaultStep() const;
+
+    /**
+     * Returns the recommended page size (when hitting pgup/pgdn)
+     *  in spin buttons displaying units of this type.
+     */
     double        getDefaultPage() const;
 
+    /**
+     *  Returns the conversion factor required to convert values
+     *  of the currently selected unit into units of type
+     *  new_unit_abbr.
+     */
     double        getConversion(Glib::ustring const &new_unit_abbr, Glib::ustring const &old_unit_abbr = "no_unit") const;
 
+    /**
+     * Returns true if the selected unit is not dimensionless 
+     *  (false for %, true for px, pt, cm, etc).
+     */
     bool          isAbsolute() const;
+
+    /**
+     * Returns true if the selected unit is radial (deg or rad).
+     */
     bool          isRadial() const;
 
     UnitTable     &getUnitTable() {return _unit_table;}
diff --git a/src/ui/widget/zoom-status.cpp b/src/ui/widget/zoom-status.cpp
index c6d6f19a3..fa8191671 100644
--- a/src/ui/widget/zoom-status.cpp
+++ b/src/ui/widget/zoom-status.cpp
@@ -1,7 +1,4 @@
-/** \file
- * Gtkmm facade/wrapper around zoom_status code that formerly lived
- * in desktop-widget.cpp
- *
+/*
  * Authors:
  *   Ralf Stephan <ralf@ark.in-berlin.de>
  *   Lauris Kaplinski <lauris@kaplinski.com>
diff --git a/src/uri.cpp b/src/uri.cpp
index a5aec6f2d..de6a454ec 100644
--- a/src/uri.cpp
+++ b/src/uri.cpp
@@ -1,7 +1,4 @@
-/**
- * \file
- * Classes for representing and manipulating URIs as per RFC 2396.
- *
+/*
  * Authors:
  *   MenTaLguY <mental@rydia.net>
  *   Jon A. Cruz <jon@joncruz.org>
@@ -17,19 +14,11 @@
 
 namespace Inkscape {
 
-/**
- * Copy constructor.
- */
 URI::URI(const URI &uri) {
     uri._impl->reference();
     _impl = uri._impl;
 }
 
-/**
- * Constructor from a C-style ASCII string.
- *
- * @param preformed Properly quoted C-style string to be represented.
- */
 URI::URI(gchar const *preformed) throw(BadURIException) {
     xmlURIPtr uri;
     if (!preformed) {
@@ -42,17 +31,10 @@ URI::URI(gchar const *preformed) throw(BadURIException) {
     _impl = Impl::create(uri);
 }
 
-
-/**
- * Destructor.
- */
 URI::~URI() {
     _impl->unreference();
 }
 
-/**
- * Assignment operator.
- */
 URI &URI::operator=(URI const &uri) {
 // No check for self-assignment needed, as _impl refcounting increments first.
     uri._impl->reference();
@@ -85,35 +67,15 @@ void URI::Impl::unreference() {
     }
 }
 
-/**
- * Determines if the URI represented is an 'opaque' URI.
- *
- * @return \c true if the URI is opaque, \c false if hierarchial.
- */
 bool URI::Impl::isOpaque() const {
     bool opq = !isRelative() && (getOpaque() != NULL);
     return opq;
 }
 
-/**
- * Determines if the URI represented is 'relative' as per RFC 2396.
- *
- * Relative URI references are distinguished by not begining with a
- * scheme name.
- *
- * @return \c true if the URI is relative, \c false if it is absolute.
- */
 bool URI::Impl::isRelative() const {
     return !_uri->scheme;
 }
 
-/**
- * Determines if the relative URI represented is a 'net-path' as per RFC 2396.
- *
- * A net-path is one that starts with "\\".
- *
- * @return \c true if the URI is relative and a net-path, \c false otherwise.
- */
 bool URI::Impl::isNetPath() const {
     bool isNet = false;
     if ( isRelative() )
@@ -124,13 +86,6 @@ bool URI::Impl::isNetPath() const {
     return isNet;
 }
 
-/**
- * Determines if the relative URI represented is a 'relative-path' as per RFC 2396.
- *
- * A relative-path is one that starts with no slashes.
- *
- * @return \c true if the URI is relative and a relative-path, \c false otherwise.
- */
 bool URI::Impl::isRelativePath() const {
     bool isRel = false;
     if ( isRelative() )
@@ -141,13 +96,6 @@ bool URI::Impl::isRelativePath() const {
     return isRel;
 }
 
-/**
- * Determines if the relative URI represented is a 'absolute-path' as per RFC 2396.
- *
- * An absolute-path is one that starts with a single "\".
- *
- * @return \c true if the URI is relative and an absolute-path, \c false otherwise.
- */
 bool URI::Impl::isAbsolutePath() const {
     bool isAbs = false;
     if ( isRelative() )
@@ -243,13 +191,6 @@ URI URI::from_native_filename(gchar const *path) throw(BadURIException) {
     return result;
 }
 
-/**
- * Returns a glib string version of this URI.
- *
- * The returned string must be freed with \c g_free().
- *
- * @return a glib string version of this URI.
- */
 gchar *URI::Impl::toString() const {
     xmlChar *string = xmlSaveUri(_uri);
     if (string) {
diff --git a/src/uri.h b/src/uri.h
index 159cd1cfc..6866f58a1 100644
--- a/src/uri.h
+++ b/src/uri.h
@@ -23,28 +23,98 @@ namespace Inkscape {
  */
 class URI {
 public:
+
+    /**
+     * Copy constructor.
+     */
     URI(URI const &uri);
+
+    /**
+     * Constructor from a C-style ASCII string.
+     *
+     * @param preformed Properly quoted C-style string to be represented.
+     */
     explicit URI(gchar const *preformed) throw(BadURIException);
+
+    /**
+     * Destructor.
+     */
     ~URI();
 
+    /**
+     * Determines if the URI represented is an 'opaque' URI.
+     *
+     * @return \c true if the URI is opaque, \c false if hierarchial.
+     */
     bool isOpaque() const { return _impl->isOpaque(); }
+
+    /**
+     * Determines if the URI represented is 'relative' as per RFC 2396.
+     *
+     * Relative URI references are distinguished by not begining with a
+     * scheme name.
+     *
+     * @return \c true if the URI is relative, \c false if it is absolute.
+     */
     bool isRelative() const { return _impl->isRelative(); }
+
+    /**
+     * Determines if the relative URI represented is a 'net-path' as per RFC 2396.
+     *
+     * A net-path is one that starts with "\\".
+     *
+     * @return \c true if the URI is relative and a net-path, \c false otherwise.
+     */
     bool isNetPath() const { return _impl->isNetPath(); }
+
+    /**
+     * Determines if the relative URI represented is a 'relative-path' as per RFC 2396.
+     *
+     * A relative-path is one that starts with no slashes.
+     *
+     * @return \c true if the URI is relative and a relative-path, \c false otherwise.
+     */
     bool isRelativePath() const { return _impl->isRelativePath(); }
+
+    /**
+     * Determines if the relative URI represented is a 'absolute-path' as per RFC 2396.
+     *
+     * An absolute-path is one that starts with a single "\".
+     *
+     * @return \c true if the URI is relative and an absolute-path, \c false otherwise.
+     */
     bool isAbsolutePath() const { return _impl->isAbsolutePath(); }
+
     const gchar *getScheme() const { return _impl->getScheme(); }
+
     const gchar *getPath() const { return _impl->getPath(); }
+
     const gchar *getQuery() const { return _impl->getQuery(); }
+
     const gchar *getFragment() const { return _impl->getFragment(); }
+
     const gchar *getOpaque() const { return _impl->getOpaque(); }
 
     static URI fromUtf8( gchar const* path ) throw (BadURIException);
+
     static URI from_native_filename(gchar const *path) throw(BadURIException);
+
     static gchar *to_native_filename(gchar const* uri) throw(BadURIException);
 
     gchar *toNativeFilename() const throw(BadURIException);
+
+    /**
+     * Returns a glib string version of this URI.
+     *
+     * The returned string must be freed with \c g_free().
+     *
+     * @return a glib string version of this URI.
+     */
     gchar *toString() const { return _impl->toString(); }
 
+    /**
+     * Assignment operator.
+     */
     URI &operator=(URI const &uri);
 
 private:
diff --git a/src/util/expression-evaluator.cpp b/src/util/expression-evaluator.cpp
index 87937be9a..37e9d6cc1 100644
--- a/src/util/expression-evaluator.cpp
+++ b/src/util/expression-evaluator.cpp
@@ -22,46 +22,6 @@
  * <http://www.gnu.org/licenses/>.
  */
 
-/** Introducing eevl eva, the evaluator. A straightforward recursive
- * descent parser, no fuss, no new dependencies. The lexer is hand
- * coded, tedious, not extremely fast but works. It evaluates the
- * expression as it goes along, and does not create a parse tree or
- * anything, and will not optimize anything. It uses doubles for
- * precision, with the given use case, that's enough to combat any
- * rounding errors (as opposed to optimizing the evalutation).
- *
- * It relies on external unit resolving through a callback and does
- * elementary dimensionality constraint check (e.g. "2 mm + 3 px * 4
- * in" is an error, as L + L^2 is a missmatch). It uses g_strtod() for numeric
- * conversions and it's non-destructive in terms of the paramters, and
- * it's reentrant.
- *
- * EBNF:
- *
- *   expression    ::= term { ('+' | '-') term }*  |
- *                     <empty string> ;
- *
- *   term          ::= signed factor { ( '*' | '/' ) signed factor }* ;
- *
- *   signed factor ::= ( '+' | '-' )? factor ;
- *
- *   unit factor   ::= factor unit? ;
- *
- *   factor        ::= number | '(' expression ')' ;
- *
- *   number        ::= ? what g_strtod() consumes ? ;
- *
- *   unit          ::= ? what not g_strtod() consumes and not whitespace ? ;
- *
- * The code should match the EBNF rather closely (except for the
- * non-terminal unit factor, which is inlined into factor) for
- * maintainability reasons.
- *
- * It will allow 1++1 and 1+-1 (resulting in 2 and 0, respectively),
- * but I figured one might want that, and I don't think it's going to
- * throw anyone off.
- */
-
 #include "config.h"
 
 #include "util/expression-evaluator.h"
diff --git a/src/util/expression-evaluator.h b/src/util/expression-evaluator.h
index 90789a25f..4b1065268 100644
--- a/src/util/expression-evaluator.h
+++ b/src/util/expression-evaluator.h
@@ -22,8 +22,8 @@
  * <http://www.gnu.org/licenses/>.
  */
 
-#ifndef __GIMP_EEVL_H__
-#define __GIMP_EEVL_H__
+#ifndef SEEN_GIMP_EEVL_H
+#define SEEN_GIMP_EEVL_H
 
 #include "util/units.h"
 
@@ -31,6 +31,48 @@
 #include <sstream>
 #include <string>
 
+/**
+ * @file
+ * Introducing eevl eva, the evaluator. A straightforward recursive
+ * descent parser, no fuss, no new dependencies. The lexer is hand
+ * coded, tedious, not extremely fast but works. It evaluates the
+ * expression as it goes along, and does not create a parse tree or
+ * anything, and will not optimize anything. It uses doubles for
+ * precision, with the given use case, that's enough to combat any
+ * rounding errors (as opposed to optimizing the evalutation).
+ *
+ * It relies on external unit resolving through a callback and does
+ * elementary dimensionality constraint check (e.g. "2 mm + 3 px * 4
+ * in" is an error, as L + L^2 is a missmatch). It uses g_strtod() for numeric
+ * conversions and it's non-destructive in terms of the paramters, and
+ * it's reentrant.
+ *
+ * EBNF:
+ *
+ *   expression    ::= term { ('+' | '-') term }*  |
+ *                     <empty string> ;
+ *
+ *   term          ::= signed factor { ( '*' | '/' ) signed factor }* ;
+ *
+ *   signed factor ::= ( '+' | '-' )? factor ;
+ *
+ *   unit factor   ::= factor unit? ;
+ *
+ *   factor        ::= number | '(' expression ')' ;
+ *
+ *   number        ::= ? what g_strtod() consumes ? ;
+ *
+ *   unit          ::= ? what not g_strtod() consumes and not whitespace ? ;
+ *
+ * The code should match the EBNF rather closely (except for the
+ * non-terminal unit factor, which is inlined into factor) for
+ * maintainability reasons.
+ *
+ * It will allow 1++1 and 1+-1 (resulting in 2 and 0, respectively),
+ * but I figured one might want that, and I don't think it's going to
+ * throw anyone off.
+ */
+
 namespace Inkscape {
 namespace Util {
 
@@ -77,4 +119,4 @@ protected:
 }
 }
 
-#endif /* __GIMP_EEVL_H__ */
+#endif // SEEN_GIMP_EEVL_H