Documentation update pass.

(bzr r10692)

24 files changed, 88 insertions, 91 deletions

diff --git a/src/bind/javabind.cpp b/src/bind/javabind.cpp
index f1a3423fe..41da00e81 100644
--- a/src/bind/javabind.cpp
+++ b/src/bind/javabind.cpp
@@ -3,6 +3,16 @@
  * This is a simple mechanism to bind Inkscape to Java, and thence
  * to all of the nice things that can be layered upon that.
  *
+ * Note: We must limit Java or JVM-specific code to this file
+ * and to dobinding.cpp.  It should be hidden from javabind.h
+ * 
+ * This file is mostly about getting things up and running, and
+ * providing the basic C-to-Java hooks.
+ *   
+ * dobinding.cpp will have the rote and repetitious
+ * class-by-class binding   
+ */  
+/*
  * Authors:
  *   Bob Jamison
  *
@@ -59,16 +69,6 @@
 #include <inkscape.h>
 #include <xml/repr.h>
 
-/**
- * Note: We must limit Java or JVM-specific code to this file
- * and to dobinding.cpp.  It should be hidden from javabind.h
- * 
- * This file is mostly about getting things up and running, and
- * providing the basic C-to-Java hooks.
- *   
- * dobinding.cpp will have the rote and repetitious
- * class-by-class binding   
- */  
 
 
 namespace Inkscape
diff --git a/src/composite-undo-stack-observer.cpp b/src/composite-undo-stack-observer.cpp
index 6af34d92a..383e08cd8 100644
--- a/src/composite-undo-stack-observer.cpp
+++ b/src/composite-undo-stack-observer.cpp
@@ -1,6 +1,4 @@
-/**
- * Aggregates undo stack observers for convenient management and triggering in SPDocument
- *
+/*
  * Heavily inspired by Inkscape::XML::CompositeNodeObserver.
  *
  * Authors:
diff --git a/src/composite-undo-stack-observer.h b/src/composite-undo-stack-observer.h
index cd00d4211..c34ab7234 100644
--- a/src/composite-undo-stack-observer.h
+++ b/src/composite-undo-stack-observer.h
@@ -1,8 +1,4 @@
-/**
- * Aggregates undo stack observers for management and triggering in SPDocument
- *
- * Heavily inspired by Inkscape::XML::CompositeNodeObserver.
- *
+/*
  * Authors:
  * David Yip <yipdw@rose-hulman.edu>
  *
@@ -11,8 +7,8 @@
  * Released under GNU GPL, read the file 'COPYING' for more information
  */
 
-#ifndef __COMPOSITE_UNDO_COMMIT_OBSERVER_H__
-#define __COMPOSITE_UNDO_COMMIT_OBSERVER_H__
+#ifndef SEEN_COMPOSITE_UNDO_COMMIT_OBSERVER_H
+#define SEEN_COMPOSITE_UNDO_COMMIT_OBSERVER_H
 
 #include "gc-alloc.h"
 #include "gc-managed.h"
@@ -27,6 +23,8 @@ class Event;
 /**
  * Aggregates UndoStackObservers for management and triggering in an SPDocument's undo/redo
  * system.
+ *
+ * Heavily inspired by Inkscape::XML::CompositeNodeObserver.
  */
 class CompositeUndoStackObserver : public UndoStackObserver {
 public:
@@ -181,4 +179,4 @@ private:
 
 }
 
-#endif
+#endif // SEEN_COMPOSITE_UNDO_COMMIT_OBSERVER_H
diff --git a/src/console-output-undo-observer.cpp b/src/console-output-undo-observer.cpp
index 2cbac74f8..92c937273 100644
--- a/src/console-output-undo-observer.cpp
+++ b/src/console-output-undo-observer.cpp
@@ -1,4 +1,4 @@
-/**
+/*
  * Inkscape::ConsoleOutputUndoObserver - observer for tracing calls to
  * SPDocumentUndo::undo, SPDocumentUndo::redo, SPDocumentUndo::maybe_done
  *
diff --git a/src/console-output-undo-observer.h b/src/console-output-undo-observer.h
index b5c08a8b5..f47a86534 100644
--- a/src/console-output-undo-observer.h
+++ b/src/console-output-undo-observer.h
@@ -1,7 +1,4 @@
-/**
- * Inkscape::ConsoleOutputUndoObserver - observer for tracing calls to
- * SPDocumentUndo::undo, SPDocumentUndo::redo, SPDocumentUndo::maybe_done
- *
+/*
  * Authors:
  * David Yip <yipdw@alumni.rose-hulman.edu>
  *   Abhishek Sharma
@@ -18,6 +15,11 @@
 
 namespace Inkscape {
 
+/**
+ * Inkscape::ConsoleOutputUndoObserver - observer for tracing calls to
+ * SPDocumentUndo::undo, SPDocumentUndo::redo, SPDocumentUndo::maybe_done.
+ *
+ */
 class ConsoleOutputUndoObserver : public UndoStackObserver {
 public:
     ConsoleOutputUndoObserver() : UndoStackObserver() { }
diff --git a/src/libavoid/vpsc.h b/src/libavoid/vpsc.h
index 4d6d8ce61..da837c1f8 100644
--- a/src/libavoid/vpsc.h
+++ b/src/libavoid/vpsc.h
@@ -181,10 +181,13 @@ public:
     const bool equality;
     bool unsatisfiable;
 };
-/*
+
+/**
  * 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
+ * are satisfied by keeping the variables fixed relative to one another.
+ *
+ * @todo check on this class being copy-n-paste duplicated.
  */
 class Blocks : public std::set<Block*>
 {
diff --git a/src/libcola/straightener.cpp b/src/libcola/straightener.cpp
index 7a1020781..0ecd82faa 100644
--- a/src/libcola/straightener.cpp
+++ b/src/libcola/straightener.cpp
@@ -3,8 +3,10 @@
 ** vim: ts=4 sw=4 et tw=0 wm=0
 */
 /**
- * \brief Functions to automatically generate constraints for the
+ * Functions to automatically generate constraints for the
  * rectangular node overlap removal problem.
+ */
+/*
  *
  * Authors:
  *   Tim Dwyer <tgdwyer@gmail.com>
diff --git a/src/libvpsc/blocks.h b/src/libvpsc/blocks.h
index bfe99f271..e3223822e 100644
--- a/src/libvpsc/blocks.h
+++ b/src/libvpsc/blocks.h
@@ -1,10 +1,4 @@
-/**
- * \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
- *
+/*
  * Authors:
  *   Tim Dwyer <tgdwyer@gmail.com>
  *
@@ -24,13 +18,17 @@
 #include <list>
 
 namespace vpsc {
+
 class Block;
 class Variable;
 class Constraint;
+
 /**
  * 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
+ * are satisfied by keeping the variables fixed relative to one another.
+ *
+ * @todo check on this class being copy-n-paste duplicated.
  */
 class Blocks : public std::set<Block*>
 {
diff --git a/src/libvpsc/constraint.cpp b/src/libvpsc/constraint.cpp
index af5da941a..2bd173155 100644
--- a/src/libvpsc/constraint.cpp
+++ b/src/libvpsc/constraint.cpp
@@ -1,7 +1,4 @@
-/**
- * \brief A constraint determines a minimum or exact spacing required between
- * two variables.
- *
+/*
  * Authors:
  *   Tim Dwyer <tgdwyer@gmail.com>
  *
diff --git a/src/libvpsc/constraint.h b/src/libvpsc/constraint.h
index 8a8529d7e..a3173359c 100644
--- a/src/libvpsc/constraint.h
+++ b/src/libvpsc/constraint.h
@@ -1,7 +1,4 @@
-/**
- * \brief A constraint determines a minimum or exact spacing required between
- * two variables.
- *
+/*
  * Authors:
  *   Tim Dwyer <tgdwyer@gmail.com>
  *
@@ -17,6 +14,11 @@
 #include "variable.h"
 namespace vpsc {
 
+/**
+ * A constraint determines a minimum or exact spacing required between
+ * two variables.
+ *
+ */
 class Constraint
 {
 	friend std::ostream& operator <<(std::ostream &os,const Constraint &c);
diff --git a/src/libvpsc/generate-constraints.cpp b/src/libvpsc/generate-constraints.cpp
index 0c35ab51c..8dd2d9331 100644
--- a/src/libvpsc/generate-constraints.cpp
+++ b/src/libvpsc/generate-constraints.cpp
@@ -1,6 +1,9 @@
 /**
- * \brief Functions to automatically generate constraints for the
+ * @file
+ * Functions to automatically generate constraints for the
  * rectangular node overlap removal problem.
+ */
+/*
  *
  * Authors:
  *   Tim Dwyer <tgdwyer@gmail.com>
diff --git a/src/libvpsc/generate-constraints.h b/src/libvpsc/generate-constraints.h
index 8b858af3f..b8d7cdcd9 100644
--- a/src/libvpsc/generate-constraints.h
+++ b/src/libvpsc/generate-constraints.h
@@ -1,6 +1,10 @@
 /**
- * \brief Functions to automatically generate constraints for the
+ * @file
+ * Functions to automatically generate constraints for the
  * rectangular node overlap removal problem.
+ */
+/* TODO replace file comment with appropriate doc comment on vpsc::Rectangle */
+/*
  *
  * Authors:
  *   Tim Dwyer <tgdwyer@gmail.com>
diff --git a/src/ui/dialog/glyphs.cpp b/src/ui/dialog/glyphs.cpp
index fc0912539..6d823e6de 100644
--- a/src/ui/dialog/glyphs.cpp
+++ b/src/ui/dialog/glyphs.cpp
@@ -1,7 +1,3 @@
-/**
- * Glyph selector dialog.
- */
-
 /* Authors:
  *   Jon A. Cruz
  *   Abhishek Sharma
diff --git a/src/ui/dialog/glyphs.h b/src/ui/dialog/glyphs.h
index 1440a693f..5dbfb9af5 100644
--- a/src/ui/dialog/glyphs.h
+++ b/src/ui/dialog/glyphs.h
@@ -1,7 +1,3 @@
-/**
- * Glyph selector dialog.
- */
-
 /* Authors:
  *   Jon A. Cruz
  *
@@ -40,7 +36,6 @@ class GlyphColumns;
 /**
  * A panel that displays character glyphs.
  */
-
 class GlyphsPanel : public Inkscape::UI::Widget::Panel
 {
 public:
diff --git a/src/widgets/dash-selector.h b/src/widgets/dash-selector.h
index 6db66f805..1fadf4385 100644
--- a/src/widgets/dash-selector.h
+++ b/src/widgets/dash-selector.h
@@ -1,9 +1,6 @@
-#ifndef __SP_DASH_SELECTOR_NEW_H__
-#define __SP_DASH_SELECTOR_NEW_H__
+#ifndef SEEN_SP_DASH_SELECTOR_NEW_H
+#define SEEN_SP_DASH_SELECTOR_NEW_H
 
-/** @file
- * @brief Option menu for selecting dash patterns
- */
 /* Authors:
  *   Lauris Kaplinski <lauris@kaplinski.com>
  *   Maximilian Albert <maximilian.albert> (gtkmm-ification)
@@ -25,6 +22,9 @@ class Adjustment;
 }
 
 // TODO: should we rather derive this from OptionMenu and add the spinbutton somehow else?
+/**
+ * Option menu for selecting dash patterns.
+ */
 class SPDashSelector : public Gtk::HBox {
 public:
     SPDashSelector();
@@ -47,7 +47,7 @@ private:
     static gchar const *const _prefs_path;
 };
 
-#endif
+#endif // SEEN_SP_DASH_SELECTOR_NEW_H
 
 /*
   Local Variables:
diff --git a/src/widgets/eek-preview.cpp b/src/widgets/eek-preview.cpp
index 5de246f6b..d867647ed 100644
--- a/src/widgets/eek-preview.cpp
+++ b/src/widgets/eek-preview.cpp
@@ -1,7 +1,3 @@
-/**
- * @file
- * EEK preview stuff.
- */
 /* ***** BEGIN LICENSE BLOCK *****
  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  *
diff --git a/src/widgets/eek-preview.h b/src/widgets/eek-preview.h
index c15f25eb6..7275ab9b4 100644
--- a/src/widgets/eek-preview.h
+++ b/src/widgets/eek-preview.h
@@ -1,6 +1,3 @@
-/** @file
- * @brief EEK preview stuff
- */
 /* ***** BEGIN LICENSE BLOCK *****
  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  *
@@ -43,6 +40,11 @@
 #include <gdk/gdk.h>
 #include <gtk/gtk.h>
 
+/**
+ * @file
+ * Generic implementation of a object that can be shown by a preview.
+ */
+
 G_BEGIN_DECLS
 
 
diff --git a/src/widgets/ege-paint-def.cpp b/src/widgets/ege-paint-def.cpp
index 36777d16a..c4325659d 100644
--- a/src/widgets/ege-paint-def.cpp
+++ b/src/widgets/ege-paint-def.cpp
@@ -1,7 +1,3 @@
-/**
- * @file
- * EGE paint definition.
- */
 /* ***** BEGIN LICENSE BLOCK *****
  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  *
diff --git a/src/widgets/ege-paint-def.h b/src/widgets/ege-paint-def.h
index 32f92ac3d..856146019 100644
--- a/src/widgets/ege-paint-def.h
+++ b/src/widgets/ege-paint-def.h
@@ -1,6 +1,3 @@
-/** @file
- * @brief EGE paint definition
- */
 /* ***** BEGIN LICENSE BLOCK *****
  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  *
@@ -49,6 +46,9 @@ namespace ege
 typedef void (*ColorCallback)( void* data );
 
 
+/**
+ * Pure data representation of a color definition.
+ */
 class PaintDef
 {
 public:
diff --git a/src/widgets/sp-attribute-widget.cpp b/src/widgets/sp-attribute-widget.cpp
index 9cdf9fab3..b8ac50092 100644
--- a/src/widgets/sp-attribute-widget.cpp
+++ b/src/widgets/sp-attribute-widget.cpp
@@ -1,7 +1,3 @@
-/**
- * @file
- * Widget that listens and modifies repr attributes.
- */
 /* Authors:
  *  Lauris Kaplinski <lauris@ximian.com>
  *   Abhishek Sharma
diff --git a/src/widgets/sp-attribute-widget.h b/src/widgets/sp-attribute-widget.h
index 93342ff4e..a4acf9504 100644
--- a/src/widgets/sp-attribute-widget.h
+++ b/src/widgets/sp-attribute-widget.h
@@ -1,5 +1,6 @@
-/** @file
- * @brief Widget that listens and modifies repr attributes
+/**
+ * @file
+ * Widget that listens and modifies repr attributes.
  */
 /* Authors:
  *  Lauris Kaplinski <lauris@kaplinski.com>
diff --git a/src/widgets/stroke-style.cpp b/src/widgets/stroke-style.cpp
index 3594e2049..488b10666 100644
--- a/src/widgets/stroke-style.cpp
+++ b/src/widgets/stroke-style.cpp
@@ -1,7 +1,3 @@
-/**
- * @file
- * Stroke style dialog.
- */
 /* Authors:
  *   Lauris Kaplinski <lauris@kaplinski.com>
  *   Bryce Harrington <brycehar@bryceharrington.org>
diff --git a/src/widgets/stroke-style.h b/src/widgets/stroke-style.h
index b8ab05810..882901f45 100644
--- a/src/widgets/stroke-style.h
+++ b/src/widgets/stroke-style.h
@@ -1,5 +1,6 @@
-/** @file
- * @brief  Stroke style dialog
+/**
+ * @file
+ * Widgets used in the stroke style dialog.
  */
 /* Author:
  *   Lauris Kaplinski <lauris@ximian.com>
@@ -19,9 +20,19 @@ class Widget;
 class Container;
 }
 
+/**
+ * Creates an instance of a paint style widget.
+ */
 Gtk::Widget *sp_stroke_style_paint_widget_new(void);
+
+/**
+ * Creates an instance of a line style widget.
+ */
 Gtk::Container *sp_stroke_style_line_widget_new(void);
 
+/**
+ * Switches a line or paint style widget to track the given desktop.
+ */
 void sp_stroke_style_widget_set_desktop(Gtk::Widget *widget, SPDesktop *desktop);
 
 #endif // SEEN_DIALOGS_STROKE_STYLE_H
diff --git a/src/widgets/toolbox.h b/src/widgets/toolbox.h
index a3fbddf0c..d7a1b9bd2 100644
--- a/src/widgets/toolbox.h
+++ b/src/widgets/toolbox.h
@@ -1,9 +1,7 @@
 #ifndef SEEN_TOOLBOX_H
 #define SEEN_TOOLBOX_H
 
-/**
- * \brief Main toolbox
- *
+/*
  * Authors:
  *   Lauris Kaplinski <lauris@kaplinski.com>
  *   Frank Felfe <innerspace@iname.com>
@@ -26,6 +24,9 @@ class SPEventContext;
 namespace Inkscape {
 namespace UI {
 
+/**
+ * Main toolbox source.
+ */
 class ToolboxFactory
 {
 public: