[dia] dox: improved documentation for renderers and importers

[Hans Breuer <hans src gnome org>]

commit 1ffa2a8cf966c010a8c902a4e05b4592e95c1e06
Author: Hans Breuer <hans breuer org>
Date:   Thu Sep 4 18:34:11 2014 +0200

    dox: improved documentation for renderers and importers
    
    The DiaRenderer interface is now completely documented with renderer
    implementors in mind. To support sub-grouping in the documentation some
    code needed to be moved around, but there is no functional change.
    
    Also more importers are included with the Doxygen generated documentation.

 lib/Doxyfile                              |    4 +-
 lib/create.h                              |   12 +-
 lib/dia.dox                               |   45 +--
 lib/diaimportrenderer.c                   |   10 +-
 lib/diarenderer.c                         |  426 +++++++++++++++++++++++------
 lib/diarenderer.h                         |   13 +-
 lib/diatransformrenderer.c                |   31 +-
 lib/objchange.h                           |    3 +-
 plug-ins/drs/dia-render-script-import.c   |   25 ++-
 plug-ins/drs/dia-render-script-renderer.h |    9 +
 plug-ins/pdf/pdf-import.cpp               |   14 +
 plug-ins/wpg/wpg-import.c                 |   10 +
 12 files changed, 444 insertions(+), 158 deletions(-)
---
diff --git a/lib/Doxyfile b/lib/Doxyfile
index 1147a7e..961b5ad 100644
--- a/lib/Doxyfile
+++ b/lib/Doxyfile
@@ -1,5 +1,5 @@
 PROJECT_NAME           = Dia
-PROJECT_BRIEF          = "extensible application to draw structured diagrams"
+PROJECT_BRIEF          = "extensible application to create structured diagrams"
 PROJECT_LOGO           = ../data/icons/scalable/apps/dia.svg
 
 TAB_SIZE               = 8
@@ -13,7 +13,7 @@ WARN_LOGFILE           = doxygen.log
 INPUT                  = ../lib ../objects/standard ../objects/custom \
                        ../plug-ins/python ../plug-ins/svg ../plug-ins/shape \
                        ../plug-ins/cairo ../plug-ins/layout ../plug-ins/pdf \
-                       ../plug-ins/wpg
+                       ../plug-ins/wpg ../plug-ins/drs
 #STRIP_FROM_PATH        = ../
 FILE_PATTERNS          = *.c *.h *.dox *.py *.cpp
 # define HAVE_CAIRO to get the Outline dox
diff --git a/lib/create.h b/lib/create.h
index 37065f0..aebfc05 100644
--- a/lib/create.h
+++ b/lib/create.h
@@ -22,7 +22,7 @@
  *
  * \ingroup StandardObjects
  *
- * Typical import plugins translate some vector representation of the import format
+ * Typical import plug-ins translate some vector representation of the import format
  * into _DiaObject representations. This set of functions and structures simplifies 
  * the creation of standard objects.
  */
@@ -56,15 +56,15 @@ struct _BezierCreateData {
 
 /*!
  * \brief Create a text object for the diagram.
- * @param xpos X position (in cm from the origo) of the object.
- * @param ypos Y position (in cm from the origo) of the object.
+ * @param xpos X position (in cm from the origin) of the object.
+ * @param ypos Y position (in cm from the origin) of the object.
  * \ingroup ObjectCreate
  */
 DiaObject *create_standard_text(real xpos, real ypos);
 /*!
  * \brief Create an ellipse object for the diagram
  * @param xpos top-left corner
- * @param ypos top-lef corner
+ * @param ypos top-left corner
  * @param width the horizontal diameter
  * @param height the vertical diameter
  * \ingroup ObjectCreate
@@ -104,7 +104,7 @@ DiaObject *create_standard_bezierline(int num_points, BezPoint *points,
  */
 DiaObject *create_standard_beziergon(int num_points, BezPoint *points);
 /*!
- * \brief Create a \ref _Beziergon
+ * \brief Create a \ref _StdPath
  * \ingroup ObjectCreate
  */
 DiaObject *create_standard_path(int num_points, BezPoint *points);
@@ -135,7 +135,7 @@ DiaObject *create_standard_arc(real x1, real y1, real x2, real y2,
 DiaObject *create_standard_image(real xpos, real ypos, real width, real height, char *file);
 /*!
  * \brief Create a _Group of objects given by list.
- * The objects in list must not be added to the diagra at the same time.
+ * The objects in list must not be added to the diagram at the same time.
  * \ingroup ObjectCreate
  */
 DiaObject *create_standard_group(GList *items);
diff --git a/lib/dia.dox b/lib/dia.dox
index 0d74f2f..c14497f 100644
--- a/lib/dia.dox
+++ b/lib/dia.dox
@@ -1,15 +1,16 @@
 /*!
  * \mainpage Dia Developer Documentation
 
-This documentation is describing some of the internal structure of the 
-Dia application for sofware developers intersted in extending it. 
+This documentation describes some of the internal structure of the
+Dia application for software developers interested in extending it.
 
-Dia is a highly extensible application. There are plugin mechanism to add
+Dia is a highly extensible application. There are plug-in mechanisms to add
 diagram objects by 
- - C plug-ins (\ref Objects) 
+ - C plug-ins (\ref Objects)
  - and by XML files (\ref Shapes).
 
-Import and export facilties of Dia can be extended by plug-ins 
+Import and export facilities of Dia can be extended by plug-ins by
+implementing \ref Renderers "Renderers"
  - written in C/C++ (\ref Plugins) 
  - and Python (\ref PyDia).
 
@@ -22,7 +23,7 @@ functionality by registering actions in the menu. Again by
 
 /*!
 \defgroup Objects Objects and their Building Blocks
-\brief An \ref _DiaObject "Object" describes the apperance and behavior of diagram parts
+\brief An \ref _DiaObject "Object" describes the appearance and behavior of diagram parts
 
 There are a bunch of services to help implementing Dia objects.
 
@@ -43,7 +44,7 @@ There are a bunch of services to help implementing Dia objects.
 \ingroup ObjectParts
 \brief Automatic User Interface creation and serialization of object properties
 
-The Propery System for Dia Object allows to 
+The Property System for Dia Object allows to:
  - describe type, range and user interface representation, see PropDescription.
  - build dynamic user interfaces for all object properties
  - transform data fields of DiaObject implementation into list of generic Property
@@ -54,7 +55,7 @@ The Propery System for Dia Object allows to
 /*!
 \defgroup ObjectParts Building Blocks
 \ingroup Objects Building blocks to help implementing _DiaObject and interfacing _DiaRenderer
-\brief Typical \ref _DiaObject "Objects" are assembled from exisiting building blocks like _DiaImage
+\brief Typical \ref _DiaObject "Objects" are assembled from existing building blocks like _DiaImage
 */
 
 /*!
@@ -84,23 +85,6 @@ and "connected by" (connectionpoint->connected). The former is a 0 or 1 relation
 */
 
 /*!
-\defgroup ObjectConnects Object Connections
-\ingroup Objects
-\brief Implementation details of connections between \ref _DiaObject "objects"
-
-There are two specialized objects involved in building a connection. One is a Handle, the other one 
-is a ConnectionPoint. In an existing connection between two DiaObject the Handle belongs to the 
-first ("connected to") and the ConnectionPoint belongs to second ("connected by").
-
-The "Standard - Line" DiaObject is special because it is one of only few objects which can be 
-"connected to" (has Handles) and also "connected by" (has a ConnectionPoint). 
-Note: there is an important difference between the active and the passive form.
-
-It is important to understand the difference Dia's source is making between handle->connected_to 
-and "connected by" (connectionpoint->connected). The former is a 0 or 1 relation, the latter is 0..n.
-*/
-
-/*!
 \defgroup DiagramStructure Diagrams keeping it all together
 \brief A \ref _DiagramData "Diagram" consists of at least one \ref _Layer "Layer" containing zero or more 
\ref _DiaObject "Object"
 
@@ -129,6 +113,10 @@ to help implementing rendering.
  - _DiaSvgRenderer : to create SVG format for SVG export and Shape creation
  - _DiaGdkRenderer : the _DiaGdkRenderer is the first display renderer
  - _DiaCairoRenderer : multi-format renderer based on http://cairographics.org
+ - _DiaPathRenderer : allows to convert objects into their path representation
+ - _DiaTransformRenderer : for affine transformation on the renderer API level
+ - _DiaImportRenderer : helps to write file importer for formats which are "rendering",
+   the result is a list of \ref StandardObjects
 
  */
 
@@ -140,14 +128,14 @@ to help implementing rendering.
 /*!
 \defgroup ExportFilters Export Filters
 \ingroup Plugins
-\brief Export filters are usually implmenting the \ref _DiaRenderer "renderer" interface
+\brief Export filters are usually implementing the \ref _DiaRenderer "renderer" interface
 
  */
  
 /*!
 \defgroup ImportFilters Import Filters
 \ingroup Plugins
-\brief Import filters translate an external represenation to Dia \ref _DiaObject "objects"
+\brief Import filters translate an external representation to Dia \ref _DiaObject "objects"
 
  */
  
@@ -158,10 +146,9 @@ to help implementing rendering.
 \ingroup Plugins
 
 The documentation of PyDia is self-contained with PyDia. You can use some
-example PyDia plug-ins to generate it from your local Dia installtion
+example PyDia plug-ins to generate it from your local Dia installation
 (if build with Python support)
 
 \image html PyDiaObjects.svg "PyDia Object Model" width=10cm
 
  */
-
diff --git a/lib/diaimportrenderer.c b/lib/diaimportrenderer.c
index 980ff11..95648ce 100644
--- a/lib/diaimportrenderer.c
+++ b/lib/diaimportrenderer.c
@@ -263,7 +263,7 @@ set_fillstyle (DiaRenderer *renderer, FillStyle mode)
 
 /*!
  * \brief Apply the current renderer's style to the given object
- * \memberof _DiaImportRenderer
+ * \memberof _DiaImportRenderer \private
  */
 static void
 _apply_style (DiaImportRenderer *self,
@@ -297,7 +297,7 @@ _apply_style (DiaImportRenderer *self,
 }
 /*!
  * \brief Remember the object for later use
- * \memberof _DiaImportRenderer
+ * \memberof _DiaImportRenderer \private
  */
 static void
 _push_object (DiaImportRenderer *self, DiaObject *obj)
@@ -371,7 +371,7 @@ draw_arc (DiaRenderer *renderer, Point *center,
 }
 
 /*!
- * \brief Dtroke and/or fill a rectangle
+ * \brief Stroke and/or fill a rectangle
  * \memberof _DiaImportRenderer
  */
 static void 
@@ -459,7 +459,7 @@ draw_string (DiaRenderer *renderer,
 
 /*!
  * \brief Draw an image
- * Creates an _Image object. Ownership of the passed in image is _not_ transferred,
+ * Creates an \_Image object. Ownership of the passed in image is _not_ transferred,
  * but it's pixbuf is referenced. The caller is responsible to destroy the image
  * with dia_image_unref() when it is no longer needed.
  * \memberof _DiaImportRenderer
@@ -504,7 +504,7 @@ draw_bezier (DiaRenderer *renderer,
 }
 
 /*!
- * \brief Fill a bezier shape
+ * \brief Draw/fill a bezier shape
  * Creates a _Beziergon object.
  * \memberof _DiaImportRenderer
  */
diff --git a/lib/diarenderer.c b/lib/diarenderer.c
index e2476ac..3a2aba8 100644
--- a/lib/diarenderer.c
+++ b/lib/diarenderer.c
@@ -194,6 +194,7 @@ dia_renderer_get_type (void)
 
 /*! 
  * \brief Render all the visible object in the layer
+ *
  * @param renderer explicit this pointer
  * @param layer    layer to draw
  * @param active   TRUE if it is the currently active layer
@@ -203,7 +204,8 @@ dia_renderer_get_type (void)
  * visibility, though. If an exporter wants to 'see' also invisible
  * layers this method needs to be overwritten. Also it does not pass any
  * matrix to draw_object().
- * \memberof DiaRenderer
+ *
+ * \memberof _DiaRenderer
  */
 static void
 draw_layer (DiaRenderer *renderer,
@@ -228,6 +230,15 @@ draw_layer (DiaRenderer *renderer,
   }
 }
 
+/*!
+ * \brief Render the given object with optional transformation matrix
+ *
+ * Calls _DiaObject::DrawFunc with the given renderer, if matrix is NULL.
+ * Otherwise the object is transformed with the help of _DiaTransformRenderer.
+ * A renderer capable to do affine transformation should overwrite this function.
+ *
+ * \memberof _DiaRenderer
+ */
 static void
 draw_object (DiaRenderer *renderer,
             DiaObject   *object,
@@ -338,6 +349,20 @@ dia_renderer_class_init (DiaRendererClass *klass)
   renderer_class->set_pattern = set_pattern;
 }
 
+/*!
+ * \name Renderer Required Members
+ * A few member functions of _DiaRenderer must be implemented in every derived renderer.
+ * These should be considered pure virtual although due to the C implementation actually
+ * these member functions exist put throw a warning.
+ @{
+ */
+/*!
+ * \brief Called before rendering begins.
+ *
+ * Can be used to do various pre-rendering setup.
+ *
+ * \memberof _DiaRenderer \pure
+ */
 static void 
 begin_render (DiaRenderer *object, const Rectangle *update)
 {
@@ -345,6 +370,13 @@ begin_render (DiaRenderer *object, const Rectangle *update)
              G_OBJECT_CLASS_NAME (G_OBJECT_GET_CLASS (object)));
 }
 
+/*!
+ * \brief Called after all rendering is done.
+ *
+ * Used to do various clean-ups.
+ *
+ * \memberof _DiaRenderer \pure
+ */
 static void 
 end_render (DiaRenderer *object)
 {
@@ -352,6 +384,10 @@ end_render (DiaRenderer *object)
              G_OBJECT_CLASS_NAME (G_OBJECT_GET_CLASS (object)));
 }
 
+/*!
+ * \brief Change the line width for the strokes to come
+ * \memberof _DiaRenderer \pure
+ */
 static void 
 set_linewidth (DiaRenderer *object, real linewidth)
 {
@@ -359,6 +395,10 @@ set_linewidth (DiaRenderer *object, real linewidth)
              G_OBJECT_CLASS_NAME (G_OBJECT_GET_CLASS (object)));
 }
 
+/*!
+ * \brief Change the line caps for the strokes to come
+ * \memberof _DiaRenderer \pure
+ */
 static void 
 set_linecaps (DiaRenderer *object, LineCaps mode)
 {
@@ -366,6 +406,10 @@ set_linecaps (DiaRenderer *object, LineCaps mode)
              G_OBJECT_CLASS_NAME (G_OBJECT_GET_CLASS (object)));
 }
 
+/*!
+ * \brief Change the line join mode for the strokes to come
+ * \memberof _DiaRenderer \pure
+ */
 static void 
 set_linejoin (DiaRenderer *renderer, LineJoin mode)
 {
@@ -373,6 +417,10 @@ set_linejoin (DiaRenderer *renderer, LineJoin mode)
              G_OBJECT_CLASS_NAME (G_OBJECT_GET_CLASS (renderer)));
 }
 
+/*!
+ * \brief Change line style and dash length for the strokes to come
+ * \memberof _DiaRenderer \pure
+ */
 static void 
 set_linestyle (DiaRenderer *renderer, LineStyle mode, real dash_length)
 {
@@ -380,6 +428,14 @@ set_linestyle (DiaRenderer *renderer, LineStyle mode, real dash_length)
              G_OBJECT_CLASS_NAME (G_OBJECT_GET_CLASS (renderer)));
 }
 
+/*!
+ * \brief Set the fill mode for following fills
+ *
+ * As of this writing there is only one fill mode defined, so this function
+ * might never get called, because it does not make a difference.
+ *
+ * \memberof _DiaRenderer \pure
+ */
 static void 
 set_fillstyle (DiaRenderer *renderer, FillStyle mode)
 {
@@ -387,18 +443,10 @@ set_fillstyle (DiaRenderer *renderer, FillStyle mode)
              G_OBJECT_CLASS_NAME (G_OBJECT_GET_CLASS (renderer)));
 }
 
-static void 
-set_font (DiaRenderer *renderer, DiaFont *font, real height)
-{
-  /* if it's the same font we must ref it first */
-  dia_font_ref (font);
-  if (renderer->font)
-    dia_font_unref (renderer->font);
-  renderer->font = font;
-  renderer->font_height = height;
-}
-
-
+/*!
+ * \brief Draw a single line segment
+ * \memberof _DiaRenderer \pure
+ */
 static void 
 draw_line (DiaRenderer *renderer, Point *start, Point *end, Color *color)
 {
@@ -406,47 +454,55 @@ draw_line (DiaRenderer *renderer, Point *start, Point *end, Color *color)
              G_OBJECT_CLASS_NAME (G_OBJECT_GET_CLASS (renderer)));
 }
 
+/*!
+ * \brief Fill and/or stroke a polygon
+ *
+ * The fall-back implementation of draw_polygon is mostly ignoring the fill.
+ * A derived renderer should definitely overwrite this function.
+ *
+ * \memberof _DiaRenderer
+ */
 static void 
-draw_arc (DiaRenderer *renderer, Point *center, 
-          real width, real height, real angle1, real angle2,
-          Color *color)
+draw_polygon (DiaRenderer *renderer,
+              Point *points, int num_points,
+              Color *fill, Color *stroke)
 {
-  g_warning ("%s::draw_arc not implemented!", 
-             G_OBJECT_CLASS_NAME (G_OBJECT_GET_CLASS (renderer)));
+  DiaRendererClass *klass = DIA_RENDERER_GET_CLASS (renderer);
+  int i;
+  Color *color = fill ? fill : stroke;
+
+  g_return_if_fail (num_points > 1);
+  g_return_if_fail (color != NULL);
+
+  for (i = 0; i < num_points - 1; i++)
+    klass->draw_line (renderer, &points[i+0], &points[i+1], color);
+  /* close it in any case */
+  if (   (points[0].x != points[num_points-1].x) 
+      || (points[0].y != points[num_points-1].y))
+    klass->draw_line (renderer, &points[num_points-1], &points[0], color);
 }
 
 /*!
- * \brief Stroke and/or fill a rectangle
+ * \brief Draw an arc
  *
- * This only needs to be implemented in the derived class if it differs
- * from draw_polygon. Given that draw_polygon is a required method we can
- * use that instead of forcing every inherited class to implement
- * draw_rect(), too.
+ * Draw an arc, given its center, the bounding box (widget, height),
+ * the start angle and the end angle. It's counter-clockwise if angle2>angle1
  *
- * \memberof _DiaRenderer
+ * \memberof _DiaRenderer \pure
  */
 static void 
-draw_rect (DiaRenderer *renderer,
-           Point *ul_corner, Point *lr_corner,
-           Color *fill, Color *stroke)
+draw_arc (DiaRenderer *renderer, Point *center,
+          real width, real height, real angle1, real angle2,
+          Color *color)
 {
-  if (DIA_RENDERER_GET_CLASS(renderer)->draw_polygon == &draw_polygon) {
-    g_warning ("%s::draw_rect and draw_polygon not implemented!", 
-               G_OBJECT_CLASS_NAME (G_OBJECT_GET_CLASS (renderer)));
-  } else {
-    Point corner[4];
-    /* translate to polygon */
-    corner[0] = *ul_corner;
-    corner[1].x = lr_corner->x;
-    corner[1].y = ul_corner->y;
-    corner[2] = *lr_corner;
-    corner[3].x = ul_corner->x;
-    corner[3].y = lr_corner->y;
-    /* delegate transformation and drawing */
-    DIA_RENDERER_GET_CLASS(renderer)->draw_polygon (renderer, corner, 4, fill, stroke);
-  }
+  g_warning ("%s::draw_arc not implemented!",
+             G_OBJECT_CLASS_NAME (G_OBJECT_GET_CLASS (renderer)));
 }
 
+/*!
+ * \brief Fill an arc (a pie-chart)
+ * \memberof _DiaRenderer \pure
+ */
 static void 
 fill_arc (DiaRenderer *renderer, Point *center,
           real width, real height, real angle1, real angle2,
@@ -455,7 +511,10 @@ fill_arc (DiaRenderer *renderer, Point *center,
   g_warning ("%s::fill_arc not implemented!", 
              G_OBJECT_CLASS_NAME (G_OBJECT_GET_CLASS (renderer)));
 }
-
+/*!
+ * \brief Fill and/or stroke an ellipse
+ * \memberof _DiaRenderer \pure
+ */
 static void 
 draw_ellipse (DiaRenderer *renderer, Point *center,
               real width, real height, 
@@ -465,6 +524,29 @@ draw_ellipse (DiaRenderer *renderer, Point *center,
              G_OBJECT_CLASS_NAME (G_OBJECT_GET_CLASS (renderer)));
 }
 
+/*!
+ * \brief Set the font to use for following strings
+ *
+ * This function might be called before begin_render() because it also
+ * sets the font for following get_text_width() calls.
+ *
+ * \memberof _DiaRenderer \pure
+ */
+static void
+set_font (DiaRenderer *renderer, DiaFont *font, real height)
+{
+  /* if it's the same font we must ref it first */
+  dia_font_ref (font);
+  if (renderer->font)
+    dia_font_unref (renderer->font);
+  renderer->font = font;
+  renderer->font_height = height;
+}
+
+/*!
+ * \brief Draw a string
+ * \memberof _DiaRenderer \pure
+ */
 static void 
 draw_string (DiaRenderer *renderer,
              const gchar *text, Point *pos, Alignment alignment,
@@ -474,7 +556,30 @@ draw_string (DiaRenderer *renderer,
              G_OBJECT_CLASS_NAME (G_OBJECT_GET_CLASS (renderer)));
 }
 
-/** Default implementation of draw_text */
+/*!
+ * \brief Draw an image (pixbuf)
+ * \memberof _DiaRenderer \pure
+ */
+static void
+draw_image (DiaRenderer *renderer,
+            Point *point, real width, real height,
+            DiaImage *image)
+{
+  g_warning ("%s::draw_image not implemented!",
+             G_OBJECT_CLASS_NAME (G_OBJECT_GET_CLASS (renderer)));
+}
+
+/*! @} */
+
+/*!
+ * \brief Default implementation of draw_text
+ *
+ * The default implementation of draw_text() splits the given _Text object
+ * into single lines and passes them to draw_text_line().
+ * A Renderer with a concept of multi-line text should overwrite it.
+ *
+ * \memberof _DiaRenderer
+ */
 static void 
 draw_text (DiaRenderer *renderer,
           Text *text) 
@@ -496,7 +601,14 @@ draw_text (DiaRenderer *renderer,
   }
 }
 
-/** Default implementation of draw_text_line */
+/*!
+ * \brief Default implementation of draw_text_line
+ *
+ * The default implementation of draw_text_line() just calls set_font() and
+ * draw_string().
+ *
+ * \memberof _DiaRenderer
+ */
 static void 
 draw_text_line (DiaRenderer *renderer,
                TextLine *text_line, Point *pos, Alignment alignment, Color *color) 
@@ -511,16 +623,6 @@ draw_text_line (DiaRenderer *renderer,
                                                color);
 }
 
-static void 
-draw_image (DiaRenderer *renderer,
-            Point *point, real width, real height,
-            DiaImage *image)
-{
-  g_warning ("%s::draw_image not implemented!", 
-             G_OBJECT_CLASS_NAME (G_OBJECT_GET_CLASS (renderer)));
-}
-
-
 /*
  * medium level functions, implemented by the above
  */
@@ -678,7 +780,28 @@ approximate_bezier (BezierApprox *bezier,
     }
 }
 
-/* bezier approximation with straight lines */
+/*!
+ * \name Medium Level Methods Usually Overwritten by Modern Renderer
+ *
+ * The medium level renderer methods have a working fall-back implementation to
+ * give the same visual appearance as native member function implementations.
+ * However these functions should be overwritten, if the goal is further processing
+ * or optimized output.
+ *
+ * @{
+ */
+/*!
+ * \brief Draw a bezier curve, given it's control points
+ *
+ * The first BezPoint must be of type MOVE_TO, and no other ones may be
+ * MOVE_TOs. If further holes are supported by a specific renderer should
+ * be checked with _DiaRenderer::is_capable_to(RENDER_HOLES).
+ *
+ * The default implementation of draw_bezier() converts the given path
+ * into a polyline approximation and calls draw_polyline().
+ *
+ * \memberof _DiaRenderer
+ */
 static void 
 draw_bezier (DiaRenderer *renderer,
              BezPoint *points, int numpoints,
@@ -705,6 +828,15 @@ draw_bezier (DiaRenderer *renderer,
                                                     color);
 }
 
+/*!
+ * \brief Fill and/or stroke a closed bezier curve
+ *
+ * The default implementation can only handle a single MOVE_TO at the
+ * first point. It emulates the actual drawing with an approximated
+ * polyline.
+ *
+ * \memberof _DiaRenderer
+ */
 static void 
 draw_beziergon (DiaRenderer *renderer,
                 BezPoint *points, int numpoints,
@@ -733,7 +865,46 @@ draw_beziergon (DiaRenderer *renderer,
                                                      bezier->currpoint,
                                                      fill, stroke);
 }
+/*!
+ * \brief Stroke and/or fill a rectangle
+ *
+ * This only needs to be implemented in the derived class if it differs
+ * from draw_polygon. Given that draw_polygon is a required method we can
+ * use that instead of forcing every inherited class to implement
+ * draw_rect(), too.
+ *
+ * \memberof _DiaRenderer \pure
+ */
+static void
+draw_rect (DiaRenderer *renderer,
+           Point *ul_corner, Point *lr_corner,
+           Color *fill, Color *stroke)
+{
+  if (DIA_RENDERER_GET_CLASS(renderer)->draw_polygon == &draw_polygon) {
+    g_warning ("%s::draw_rect and draw_polygon not implemented!",
+               G_OBJECT_CLASS_NAME (G_OBJECT_GET_CLASS (renderer)));
+  } else {
+    Point corner[4];
+    /* translate to polygon */
+    corner[0] = *ul_corner;
+    corner[1].x = lr_corner->x;
+    corner[1].y = ul_corner->y;
+    corner[2] = *lr_corner;
+    corner[3].x = ul_corner->x;
+    corner[3].y = lr_corner->y;
+    /* delegate transformation and drawing */
+    DIA_RENDERER_GET_CLASS(renderer)->draw_polygon (renderer, corner, 4, fill, stroke);
+  }
+}
 
+/*!
+ * \brief Draw a polyline with the given color
+ *
+ * The default implementation is delegating the drawing to consecutive
+ * calls to draw_line().
+ *
+ * \memberof _DiaRenderer
+ */
 static void 
 draw_polyline (DiaRenderer *renderer,
                Point *points, int num_points,
@@ -769,9 +940,13 @@ calculate_min_radius( Point *p1, Point *p2, Point *p3 )
   return (c*sin(a/2));
 }
 
-/** Draw a polyline with optionally rounded corners.
- *  Based on draw_line and draw_arc, but uses draw_polyline when
- *  the rounding is too small.
+/*!
+ * \brief Draw a polyline with optionally rounded corners
+ *
+ * Default implementation based on draw_line() and draw_arc(), but uses
+ * draw_polyline when the rounding is too small.
+ *
+ * \memberof _DiaRenderer
  */
 static void
 draw_rounded_polyline (DiaRenderer *renderer,
@@ -827,30 +1002,15 @@ draw_rounded_polyline (DiaRenderer *renderer,
 }
 
 /*!
- * \brief Fallback implementation of draw_polygon mostly ignoring the fill
+ * \brief Fill and/or stroke a rectangle with rounded corners
+ *
+ * Default implementation is assembling a rectangle with potentially rounded
+ * corners from consecutive draw_arc() and draw_line() calls - if stroked.
+ * Filling is done by two overlapping rectangles and four fill_arc() calls.
+ *
  * \memberof _DiaRenderer
  */
 static void 
-draw_polygon (DiaRenderer *renderer,
-              Point *points, int num_points,
-              Color *fill, Color *stroke)
-{
-  DiaRendererClass *klass = DIA_RENDERER_GET_CLASS (renderer);
-  int i;
-  Color *color = fill ? fill : stroke;
-
-  g_return_if_fail (num_points > 1);
-  g_return_if_fail (color != NULL);
-
-  for (i = 0; i < num_points - 1; i++)
-    klass->draw_line (renderer, &points[i+0], &points[i+1], color);
-  /* close it in any case */
-  if (   (points[0].x != points[num_points-1].x) 
-      || (points[0].y != points[num_points-1].y))
-    klass->draw_line (renderer, &points[num_points-1], &points[0], color);
-}
-
-static void 
 draw_rounded_rect (DiaRenderer *renderer, 
                    Point *ul_corner, Point *lr_corner,
                    Color *fill, Color *stroke, real radius) 
@@ -909,7 +1069,24 @@ draw_rounded_rect (DiaRenderer *renderer,
     }
   }
 }
+/*! @} */
 
+/*!
+ * \name Draw With Arrows Methods
+ *
+ * A renderer implementation with a compatible concept of arrows should overwrite this
+ * function set to get the most high level output. For all other renderer a line with
+ * arrows will be split into multiple objects, which still will resemble the original
+ * appearance of the diagram.
+ *
+ * @{
+ */
+
+/*!
+ * \brief Draw a line fitting to the given arrows
+ *
+ * \memberof _DiaRenderer
+ */
 static void
 draw_line_with_arrows(DiaRenderer *renderer, 
                       Point *startpoint, 
@@ -964,6 +1141,11 @@ draw_line_with_arrows(DiaRenderer *renderer,
   *endpoint = oldend;
 }
 
+/*!
+ * \brief Draw a polyline fitting to the given arrows
+ *
+ * \memberof _DiaRenderer
+ */
 static void
 draw_polyline_with_arrows(DiaRenderer *renderer, 
                           Point *points, int num_points,
@@ -1016,7 +1198,7 @@ draw_polyline_with_arrows(DiaRenderer *renderer,
   }
   /* Don't draw degenerate line segments at end of line */
   if (lastline-firstline > 1) /* probably hiding a bug above, but don't try to draw a negative
-                                                                  * number of points at all, fixes bug 
#148139 */
+                              * number of points at all, fixes bug #148139 */
     DIA_RENDERER_GET_CLASS(renderer)->draw_polyline(renderer, &points[firstline], 
                                                     lastline-firstline, color);
   if (start_arrow != NULL && start_arrow->type != ARROW_NONE)
@@ -1036,6 +1218,11 @@ draw_polyline_with_arrows(DiaRenderer *renderer,
   points[lastline-1] = oldend;
 }
 
+/*!
+ * \brief Draw a rounded polyline fitting to the given arrows
+ *
+ * \memberof _DiaRenderer
+ */
 static void
 draw_rounded_polyline_with_arrows(DiaRenderer *renderer, 
                                  Point *points, int num_points,
@@ -1248,6 +1435,11 @@ is_right_hand (const Point *a, const Point *b, const Point *c)
   return point_cross(&dot1, &dot2) > 0;
 }
 
+/*!
+ * \brief Draw an arc fitting to the given arrows
+ *
+ * \memberof _DiaRenderer
+ */
 static void
 draw_arc_with_arrows (DiaRenderer *renderer, 
                       Point *startpoint, 
@@ -1365,6 +1557,11 @@ draw_arc_with_arrows (DiaRenderer *renderer,
               color, &color_white);
 }
 
+/*!
+ * \brief Draw a bezier line fitting to the given arrows
+ *
+ * \memberof _DiaRenderer
+ */
 static void
 draw_bezier_with_arrows(DiaRenderer *renderer, 
                         BezPoint *points,
@@ -1420,10 +1617,21 @@ draw_bezier_with_arrows(DiaRenderer *renderer,
   points[num_points-1].p3 = endpoint;
   
 }
+/*! @} */
 
-/*
- * Should we really provide this ? It formerly was an 'interactive op'
- * and depends on DiaRenderer::set_font() not or properly overwritten 
+/*!
+ * \name Interactive Renderer Methods
+ * @{
+ */
+/*!
+ * \brief Calculate text width of given string with previously set font
+ *
+ * Should we really provide this? It formerly was an 'interactive op'
+ * and depends on DiaRenderer::set_font() not or properly overwritten.
+ * As of this writing it is only used for cursor positioning in with
+ * an interactive renderer.
+ *
+ * \memberof _DiaRenderer
  */
 static real 
 get_text_width (DiaRenderer *renderer,
@@ -1446,6 +1654,10 @@ get_text_width (DiaRenderer *renderer,
   return ret;
 }
 
+/*!
+ * \brief Get drawing width in pixels if any
+ * \memberof _DiaRenderer \pure
+ */
 static int 
 get_width_pixels (DiaRenderer *renderer)
 {
@@ -1453,15 +1665,34 @@ get_width_pixels (DiaRenderer *renderer)
   return 0;
 }
 
+/*!
+ * \brief Get drawing height in pixels if any
+ * \memberof _DiaRenderer \pure
+ */
 static int 
 get_height_pixels (DiaRenderer *renderer)
 {
   g_return_val_if_fail (renderer->is_interactive, 0);
   return 0;
 }
+/*! @} */
 
 /*!
- * The base class has none of the advanced capabilities
+ * \brief Advertise special renderer capabilities
+ *
+ * The base class advertises none of the advanced capabilities, but it
+ * has basic transformation support in draw_object() with the help of
+ * _DiaTransformRenderer. Only an advanced renderer implementation will
+ * overwrite this method with it's own capabilities. Returning TRUE
+ * from this method usually requires to adapt at least one other member
+ * function, too. Current special capabilities are
+ *  - RENDER_HOLES : draw_beziergon() has to support multiple MOVE_TO
+ *  - RENDER_ALPHA : the alpha component of _Color is handled to create transparency
+ *  - RENDER_AFFINE : at least draw_object() to be overwritten to support affine transformations.
+ *    At some point in time also draw_text() and draw_image() need to handle at least rotation.
+ *  - RENDER_PATTERN : set_pattern() overwrite and filling with pattern instead of fill color
+ *
+ * \memberof _DiaRenderer
  */
 static gboolean 
 is_capable_to (DiaRenderer *renderer, RenderCapability cap)
@@ -1470,7 +1701,9 @@ is_capable_to (DiaRenderer *renderer, RenderCapability cap)
 }
 
 /*!
+ * \brief Set the (gradient) pattern for later fill
  * The base class has no pattern (gradient) support
+ * \memberof _DiaRenderer \pure
  */
 static void
 set_pattern (DiaRenderer *renderer, DiaPattern *pat)
@@ -1479,8 +1712,10 @@ set_pattern (DiaRenderer *renderer, DiaPattern *pat)
              G_OBJECT_CLASS_NAME (G_OBJECT_GET_CLASS (renderer)));
 }
 
-/*
- * non member functions
+/*!
+ * \brief Get the width in pixels of the drawing area (if any)
+ *
+ * \relates _DiaRenderer
  */
 int
 dia_renderer_get_width_pixels (DiaRenderer *renderer)
@@ -1488,12 +1723,25 @@ dia_renderer_get_width_pixels (DiaRenderer *renderer)
   return DIA_RENDERER_GET_CLASS(renderer)->get_width_pixels (renderer);
 }
 
+/*!
+ * \brief Get the height in pixels of the drawing area (if any)
+ *
+ * \relates _DiaRenderer
+ */
 int
 dia_renderer_get_height_pixels (DiaRenderer *renderer)
 {
   return DIA_RENDERER_GET_CLASS(renderer)->get_height_pixels (renderer);
 }
 
+/*!
+ * \brief Helper function to fill bezier with multiple BEZ_MOVE_TO
+ * A slightly improved version to split a bezier with multiple move-to into
+ * a form which can be used with _DiaRenderer not supporting RENDER_HOLES.
+ * With reasonable placement of the second movement it works well for single
+ * holes at least. There are artifacts for more complex path to render.
+ * \relates _DiaRenderer
+ */
 void
 bezier_render_fill (DiaRenderer *renderer, BezPoint *pts, int total, Color *color)
 {
@@ -1558,7 +1806,7 @@ bezier_render_fill (DiaRenderer *renderer, BezPoint *pts, int total, Color *colo
 
 /*!
  * \brief Helper function to fill bezier with multiple BEZ_MOVE_TO
- * \memberof DiaRenderer
+ * \relates _DiaRenderer
  */
 G_GNUC_UNUSED static void
 bezier_render_fill_old (DiaRenderer *renderer, BezPoint *pts, int total, Color *color)
@@ -1600,7 +1848,7 @@ bezier_render_fill_old (DiaRenderer *renderer, BezPoint *pts, int total, Color *
 
 /*!
  * \brief Helper function to stroke a bezier with multiple BEZ_MOVE_TO
- * \memberof DiaRenderer
+ * \relates _DiaRenderer
  */
 void
 bezier_render_stroke (DiaRenderer *renderer, BezPoint *pts, int total, Color *color)
diff --git a/lib/diarenderer.h b/lib/diarenderer.h
index 0f31629..af2a800 100644
--- a/lib/diarenderer.h
+++ b/lib/diarenderer.h
@@ -56,8 +56,8 @@ GType dia_renderer_get_type (void) G_GNUC_CONST;
  *
  * The Dia renderers are already realized with the GObject type system.
  * Most of the renderers are only used for export, but there are also
- * some renderers cabable of interaction (i.e. display). These are
- * extended versions providing the _DiaInteractiveRendererInterface
+ * some renderers capable of interaction (i.e. display). These are
+ * extended versions providing also the _DiaInteractiveRendererInterface
  *
  * \ingroup Renderers
  */
@@ -68,7 +68,7 @@ struct _DiaRenderer
   /*< private >*/
   DiaFont *font;
   real font_height; /* IMO It should be possible use the font's size to keep
-                     * this info, but currently _not_ : multiline text is 
+                     * this info, but currently _not_ : multi-line text is
                      * growing on every line when zoomed: BUG in font.c  --hb
                      */
   BezierApprox *bezier;
@@ -78,7 +78,7 @@ struct _DiaRenderer
  * \brief Base class for all of Dia's render facilities
  *
  * Renderers work in close cooperation with DiaObject. They provide the way to
- * make all the object drawing independent of concrete drawing backends
+ * make all the object drawing independent of concrete drawing back-ends
  */
 struct _DiaRendererClass
 {
@@ -91,7 +91,7 @@ struct _DiaRendererClass
   /*! \brief Render all the visible object in the layer */
   void (*draw_layer) (DiaRenderer*, Layer *, gboolean, Rectangle *);
   /*! Calls the objects draw function, which calls the renderer again 
-   *  Affine transforamtion is mostly done on the renderer side for matrix!=NULL */
+   *  Affine transformation is mostly done on the renderer side for matrix!=NULL */
   void (*draw_object) (DiaRenderer*, DiaObject*, DiaMatrix*);
   /*! Returns the EXACT width of text in cm, using the current font.
      There has been some confusion as to the definition of this.
@@ -169,8 +169,7 @@ struct _DiaRendererClass
    * Functions which SHOULD be implemented by specific renderer, but
    * have a default implementation based on the above functions 
    */
-  /*! Draw a bezier curve, given it's control points. The first BezPoint must 
-     be of type MOVE_TO, and no other ones may be MOVE_TO's. */
+  /*! Draw a bezier curve, given it's control points. */
   void (*draw_bezier) (DiaRenderer *renderer,
                        BezPoint *points,
                        int numpoints,
diff --git a/lib/diatransformrenderer.c b/lib/diatransformrenderer.c
index 7898492..6b4fb1d 100644
--- a/lib/diatransformrenderer.c
+++ b/lib/diatransformrenderer.c
@@ -26,22 +26,6 @@
 #include "object.h"
 #include "diapathrenderer.h"
 
-typedef struct _DiaTransformRenderer DiaTransformRenderer;
-typedef struct _DiaTransformRendererClass DiaTransformRendererClass;
-
-/*! GObject boiler plate, create runtime information */
-#define DIA_TYPE_TRANSFORM_RENDERER           (dia_transform_renderer_get_type ())
-/*! GObject boiler plate, a safe type cast */
-#define DIA_TRANSFORM_RENDERER(obj)           (G_TYPE_CHECK_INSTANCE_CAST ((obj), 
DIA_TYPE_TRANSFORM_RENDERER, DiaTransformRenderer))
-/*! GObject boiler plate, in C++ this would be the vtable */
-#define DIA_TRANSFORM_RENDERER_CLASS(klass)   (G_TYPE_CHECK_CLASS_CAST ((klass), 
DIA_TYPE_TRANSFORM_RENDERER, DiaTransformRendererClass))
-/*! GObject boiler plate, type check */
-#define DIA_IS_TRANSFORM_RENDERER(obj)        (G_TYPE_CHECK_INSTANCE_TYPE ((obj), 
DIA_TYPE_TRANSFORM_RENDERER))
-/*! GObject boiler plate, get from object to class (vtable) */
-#define DIA_TRANSFORM_RENDERER_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), 
DIA_TYPE_TRANSFORM_RENDERER, DiaTransformRendererClass))
-
-GType dia_transform_renderer_get_type (void) G_GNUC_CONST;
-
 /*!
  * \brief Renderer which does affine transform rendering
  *
@@ -64,6 +48,21 @@ struct _DiaTransformRendererClass
   DiaRendererClass parent_class; /*!< the base class */
 };
 
+typedef struct _DiaTransformRenderer DiaTransformRenderer;
+typedef struct _DiaTransformRendererClass DiaTransformRendererClass;
+
+/*! GObject boiler plate, create runtime information */
+#define DIA_TYPE_TRANSFORM_RENDERER           (dia_transform_renderer_get_type ())
+/*! GObject boiler plate, a safe type cast */
+#define DIA_TRANSFORM_RENDERER(obj)           (G_TYPE_CHECK_INSTANCE_CAST ((obj), 
DIA_TYPE_TRANSFORM_RENDERER, DiaTransformRenderer))
+/*! GObject boiler plate, in C++ this would be the vtable */
+#define DIA_TRANSFORM_RENDERER_CLASS(klass)   (G_TYPE_CHECK_CLASS_CAST ((klass), 
DIA_TYPE_TRANSFORM_RENDERER, DiaTransformRendererClass))
+/*! GObject boiler plate, type check */
+#define DIA_IS_TRANSFORM_RENDERER(obj)        (G_TYPE_CHECK_INSTANCE_TYPE ((obj), 
DIA_TYPE_TRANSFORM_RENDERER))
+/*! GObject boiler plate, get from object to class (vtable) */
+#define DIA_TRANSFORM_RENDERER_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), 
DIA_TYPE_TRANSFORM_RENDERER, DiaTransformRendererClass))
+
+GType dia_transform_renderer_get_type (void) G_GNUC_CONST;
 
 G_DEFINE_TYPE (DiaTransformRenderer, dia_transform_renderer, DIA_TYPE_RENDERER)
 
diff --git a/lib/objchange.h b/lib/objchange.h
index 7491bbf..9332626 100644
--- a/lib/objchange.h
+++ b/lib/objchange.h
@@ -21,7 +21,7 @@
  */
 /*!
  * \defgroup ObjChange Support for undo/redo
- * \brief Object implmentations need some effort to support undo/redo
+ * \brief Object implementations need some effort to support undo/redo
  * \ingroup ObjectParts
  */
 #ifndef OBJCHANGE_H
@@ -106,4 +106,3 @@ void change_list_add (ObjectChange *change_list, ObjectChange *change);
 G_END_DECLS
 
 #endif /* OBJCHANGE_H */
-
diff --git a/plug-ins/drs/dia-render-script-import.c b/plug-ins/drs/dia-render-script-import.c
index 5b54edc..00bdf14 100644
--- a/plug-ins/drs/dia-render-script-import.c
+++ b/plug-ins/drs/dia-render-script-import.c
@@ -34,6 +34,12 @@
 
 #include "dia-render-script.h"
 
+/*!
+ * \defgroup DiaRenderScriptImport Dia Render Script Import
+ * \ingroup ImportFilters
+ * \brief Importing _Layer, _DiaObject from their XML representation saved with _DrsRenderer 
+ */
+
 static real
 _parse_real (xmlNodePtr node, const char *attrib)
 {
@@ -245,6 +251,10 @@ _parse_font (xmlNodePtr node)
 
   return font;
 }
+/*!
+ * \brief Create a _DiaObject from it's rendering XML representation
+ * \ingroup DiaRenderScriptImport
+ */
 static DiaObject *
 _render_object (xmlNodePtr render, DiaContext *ctx)
 {
@@ -358,9 +368,14 @@ find_child_named (xmlNodePtr node, const char *name)
 }
 
 /*!
+ * \brief Parse _DiaObject from the given node
  * Fill a GList* with objects which is to be put in a
  * diagram or a group by the caller. 
- * Can be called recusively to allow groups in groups.
+ * Can be called recursively to allow groups in groups.
+ * This is only using the render branch of the file, if the
+ * object type is not registered with Dia. Otherwise the objects
+ * are just created from their type and properties.
+ * \ingroup DiaRenderScriptImport
  */
 static GList*
 read_items (xmlNodePtr startnode, DiaContext *ctx)
@@ -418,7 +433,13 @@ read_items (xmlNodePtr startnode, DiaContext *ctx)
   return items;
 }
 
-/* imports the given DRS file, returns TRUE if successful */
+/*!
+ * \brief Imports the given DRS file
+ * Restore a diagram from it's Dia Render Script representation. This function
+ * is handling diagram and layers creation itself and delegates the object creation
+ * to read_items().
+ * \ingroup DiaRenderScriptImport
+ */
 gboolean
 import_drs (const gchar *filename, DiagramData *dia, DiaContext *ctx, void* user_data) 
 {
diff --git a/plug-ins/drs/dia-render-script-renderer.h b/plug-ins/drs/dia-render-script-renderer.h
index 4e52080..041d7c2 100644
--- a/plug-ins/drs/dia-render-script-renderer.h
+++ b/plug-ins/drs/dia-render-script-renderer.h
@@ -34,6 +34,15 @@ GType drs_renderer_get_type (void) G_GNUC_CONST;
 typedef struct _DrsRenderer DrsRenderer;
 typedef struct _DrsRendererClass DrsRendererClass;
 
+/*!
+ * \brief Dia RenderScript Renderer
+ * The DRS renderer implements an XML file format around Dia's renderer interface.
+ * It is useful for testing of _DiaObject draw implementations. The XML output includes
+ * not only all the rendering commands, but also the object properties and types used.
+ * This can be used with the \ref DiaRenderScriptImport to restore objects from file
+ * whether the original type is available or not.
+ * \extends _DiaRenderer
+ */
 struct _DrsRenderer
 {
   DiaRenderer parent_instance;
diff --git a/plug-ins/pdf/pdf-import.cpp b/plug-ins/pdf/pdf-import.cpp
index 46fe5ed..cd16507 100644
--- a/plug-ins/pdf/pdf-import.cpp
+++ b/plug-ins/pdf/pdf-import.cpp
@@ -42,11 +42,23 @@
 #include <vector>
 
 /*!
+ * \defgroup PdfImport Dia PDF Import
+ * \ingroup ImportFilters
+ * \brief Import PDF for further processing with Dia
+ *
+ * The PDF import plug-in is built on http://poppler.freedesktop.org/ library.
+ * It is currently considered experimental because it has no means of
+ * limiting the input to something Dia can really cope with. 
+ */
+
+/*!
  * \brief A Poppler output device turning PDF to _DiaObject
  *
  * Pretty straight translation of poppler/poppler/CairoOutputDev.cc
  * to _DiaObject semantics. A lot of things in PDF can not be easily
  * mapped to Dia capabilities, so this will stay incomplete for a while.
+ *
+ * \ingroup PdfImport
  */
 class DiaOutputDev : public OutputDev
 {
@@ -676,10 +688,12 @@ DiaOutputDev::eoFill (GfxState *state)
 
 /*!
  * \brief Draw a string to _Textobj
+ *
  * To get objects more similar to what we had during export we
  * should probably use TextOutputDev. It reassembles strings
  * based on their position on the page. Or maybe Dia/cairo should
  * stop realigning single glyphs in it's output?
+ *
  * \todo Check alignment options - it's just guessed yet.
  */
 void 
diff --git a/plug-ins/wpg/wpg-import.c b/plug-ins/wpg/wpg-import.c
index 26809db..2e5b4ec 100644
--- a/plug-ins/wpg/wpg-import.c
+++ b/plug-ins/wpg/wpg-import.c
@@ -33,7 +33,17 @@
 typedef struct _WpgImportRenderer  WpgImportRenderer;
 
 /*!
+ * \defgroup WpgImport WordPerfect Graphics Import
+ * \ingroup ImportFilters
+ * \brief WordPerfect (5.1) Graphics Import
+ *
+ * The WordPerfect Graphics import is limited to the last WPG format with
+ * open documentation. As such it is mostly useful for historical graphics;)
+ */
+
+/*!
  * \brief Renderer for WordPerfect Graphics import
+ * \ingroup WpgImport
  * \extends _DiaImportRenderer
  */
 struct _WpgImportRenderer {