[dia] dox: update developer documentation for SVG renderers

[Hans Breuer <hans src gnome org>]

commit 9a373be8e813ccb11fbf9a0820f51baa8d5afc4c
Author: Hans Breuer <hans breuer org>
Date:   Tue Sep 9 21:29:59 2014 +0200

    dox: update developer documentation for SVG renderers
    
    Fix the issue marked and listed as Doxygen bug by, it was just the
    wrong name for \memberof.

 lib/diasvgrenderer.c          |   99 +++++++++++++++++++++++++++++++++++++---
 plug-ins/shape/shape-export.c |   81 ++++++++++++++++++++++++++++-----
 plug-ins/svg/render_svg.c     |   29 +++++++-----
 3 files changed, 177 insertions(+), 32 deletions(-)
---
diff --git a/lib/diasvgrenderer.c b/lib/diasvgrenderer.c
index a001591..920f405 100644
--- a/lib/diasvgrenderer.c
+++ b/lib/diasvgrenderer.c
@@ -7,7 +7,7 @@
  * diasvgrenderer.c - refactoring of the above to serve as the
  *                    base class for plug-ins/svg/render_svg.c and
  *                    plug-ins/shape/shape-export.c
- *   Copyright (C) 2002, Hans Breuer
+ *   Copyright (C) 2002-2014 Hans Breuer
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -57,7 +57,10 @@ static void
 draw_text_line(DiaRenderer *self, TextLine *text_line,
               Point *pos, Alignment alignment, Color *colour);
 
-/* DiaSvgRenderer methods */
+/*!
+ * \brief Initialize to SVG rendering defaults
+ * \memberof _DiaSvgRenderer
+ */
 static void
 begin_render(DiaRenderer *self, const Rectangle *update)
 {
@@ -166,6 +169,10 @@ _gradient_do (gpointer key,
   }
 }
 
+/*!
+ * \brief Flush all pending information to file
+ * \memberof _DiaSvgRenderer
+ */
 static void
 end_render(DiaRenderer *self)
 {
@@ -188,6 +195,10 @@ end_render(DiaRenderer *self)
   xmlFreeDoc(renderer->doc);
 }
 
+/*!
+ * \brief Only basic capabilities for the base class
+ * \memberof _DiaSvgRenderer
+ */
 static gboolean
 is_capable_to (DiaRenderer *renderer, RenderCapability cap)
 {
@@ -202,6 +213,10 @@ is_capable_to (DiaRenderer *renderer, RenderCapability cap)
   return FALSE;
 }
 
+/*!
+ * \brief Set line width
+ * \memberof _DiaSvgRenderer
+ */
 static void
 set_linewidth(DiaRenderer *self, real linewidth)
 {  /* 0 == hairline **/
@@ -213,6 +228,10 @@ set_linewidth(DiaRenderer *self, real linewidth)
     renderer->linewidth = linewidth;
 }
 
+/*!
+ * \brief Set line caps
+ * \memberof _DiaSvgRenderer
+ */
 static void
 set_linecaps(DiaRenderer *self, LineCaps mode)
 {
@@ -233,6 +252,10 @@ set_linecaps(DiaRenderer *self, LineCaps mode)
   }
 }
 
+/*!
+ * \brief Set line join
+ * \memberof _DiaSvgRenderer
+ */
 static void
 set_linejoin(DiaRenderer *self, LineJoin mode)
 {
@@ -253,6 +276,10 @@ set_linejoin(DiaRenderer *self, LineJoin mode)
   }
 }
 
+/*!
+ * \brief Set line style
+ * \memberof _DiaSvgRenderer
+ */
 static void
 set_linestyle(DiaRenderer *self, LineStyle mode, real dash_length)
 {
@@ -315,6 +342,10 @@ set_linestyle(DiaRenderer *self, LineStyle mode, real dash_length)
   }
 }
 
+/*!
+ * \brief Set fill style
+ * \memberof _DiaSvgRenderer
+ */
 static void
 set_fillstyle(DiaRenderer *self, FillStyle mode)
 {
@@ -328,6 +359,7 @@ set_fillstyle(DiaRenderer *self, FillStyle mode)
 
 /*!
  * \brief Remember the pattern for later use
+ * \memberof _DiaSvgRenderer
  */
 static void
 set_pattern(DiaRenderer *self, DiaPattern *pattern)
@@ -350,7 +382,13 @@ set_pattern(DiaRenderer *self, DiaPattern *pattern)
     g_object_unref (prev);
 }
 
-/* the return value of this function should not be saved anywhere */
+/*!
+ * \brief Get the draw style for given fill/stroke
+ *
+ * The return value of this function should not be saved anywhere
+ *
+ * \protected \memberof _DiaSvgRenderer
+ */
 static const gchar *
 get_draw_style(DiaSvgRenderer *renderer,
               Color *fill,
@@ -401,8 +439,10 @@ get_draw_style(DiaSvgRenderer *renderer,
   return str->str;
 }
 
-/* the return value of this function should not be saved anywhere */
-
+/*!
+ * \brief Draw a single line element
+ * \memberof _DiaSvgRenderer
+ */
 static void
 draw_line(DiaRenderer *self, 
          Point *start, Point *end, 
@@ -426,6 +466,10 @@ draw_line(DiaRenderer *self,
   xmlSetProp(node, (const xmlChar *)"y2", (xmlChar *) d_buf);
 }
 
+/*!
+ * \brief Draw a polyline element
+ * \memberof _DiaSvgRenderer
+ */
 static void
 draw_polyline(DiaRenderer *self, 
              Point *points, int num_points, 
@@ -451,6 +495,10 @@ draw_polyline(DiaRenderer *self,
   g_string_free(str, TRUE);
 }
 
+/*!
+ * \brief Draw a polygon element (filled and/or stroked)
+ * \memberof _DiaSvgRenderer
+ */
 static void
 draw_polygon (DiaRenderer *self, 
              Point *points, int num_points, 
@@ -479,6 +527,10 @@ draw_polygon (DiaRenderer *self,
   g_string_free(str, TRUE);
 }
 
+/*!
+ * \brief Draw a rectangle element (filled and/or stroked)
+ * \memberof _DiaSvgRenderer
+ */
 static void
 draw_rect(DiaRenderer *self, 
          Point *ul_corner, Point *lr_corner,
@@ -502,6 +554,10 @@ draw_rect(DiaRenderer *self,
   xmlSetProp(node, (const xmlChar *)"height", (xmlChar *) d_buf);
 }
 
+/*!
+ * \brief Draw an arc with a path element
+ * \memberof _DiaSvgRenderer
+ */
 static void
 draw_arc(DiaRenderer *self, 
         Point *center,
@@ -541,6 +597,10 @@ draw_arc(DiaRenderer *self,
   xmlSetProp(node, (const xmlChar *)"d", (xmlChar *) buf);
 }
 
+/*!
+ * \brief Draw an filled arc (pie chart) with a path element
+ * \memberof _DiaSvgRenderer
+ */
 static void
 fill_arc(DiaRenderer *self, 
         Point *center,
@@ -582,6 +642,10 @@ fill_arc(DiaRenderer *self,
   xmlSetProp(node, (const xmlChar *)"d", (xmlChar *) buf);
 }
 
+/*!
+ * \brief Draw an ellipse element (filled and/or stroked)
+ * \memberof _DiaSvgRenderer
+ */
 static void
 draw_ellipse(DiaRenderer *self, 
             Point *center,
@@ -676,6 +740,10 @@ _bezier(DiaRenderer *self,
   g_string_free(str, TRUE);
 }
 
+/*!
+ * \brief Draw a path element (not closed)
+ * \memberof _DiaSvgRenderer
+ */
 static void
 draw_bezier(DiaRenderer *self, 
            BezPoint *points,
@@ -685,6 +753,10 @@ draw_bezier(DiaRenderer *self,
   _bezier(self, points, numpoints, NULL, stroke, FALSE);
 }
 
+/*!
+ * \brief Draw a path element (filled and/or stroked)
+ * \memberof _DiaSvgRenderer
+ */
 static void
 draw_beziergon (DiaRenderer *self, 
                BezPoint *points,
@@ -700,6 +772,10 @@ draw_beziergon (DiaRenderer *self,
   _bezier(self, points, numpoints, fill, stroke, TRUE);
 }
 
+/*!
+ * \brief Draw a text element by delegating to draw_text_line()
+ * \memberof _DiaSvgRenderer
+ */
 static void
 draw_string(DiaRenderer *self,
            const char *text,
@@ -711,7 +787,10 @@ draw_string(DiaRenderer *self,
   text_line_destroy(text_line);
 }
 
-
+/*!
+ * \brief Draw a text element (single line)
+ * \memberof _DiaSvgRenderer
+ */
 static void
 draw_text_line(DiaRenderer *self, TextLine *text_line,
               Point *pos, Alignment alignment, Color *colour)
@@ -776,6 +855,10 @@ draw_text_line(DiaRenderer *self, TextLine *text_line,
   xmlSetProp(node, (const xmlChar*)"textLength", (xmlChar *) d_buf);
 }
 
+/*!
+ * \brief Draw an image element
+ * \memberof _DiaSvgRenderer
+ */
 static void
 draw_image(DiaRenderer *self,
           Point *point,
@@ -820,8 +903,8 @@ draw_image(DiaRenderer *self,
 }
 
 /*!
- * \brief creation of rectangles with corner radius
- * \memberof SvgRenderer
+ * \brief Draw a rectangle element (with corner rounding)
+ * \memberof _DiaSvgRenderer
  */
 static void
 draw_rounded_rect (DiaRenderer *self, 
diff --git a/plug-ins/shape/shape-export.c b/plug-ins/shape/shape-export.c
index 04726ad..e99ae05 100644
--- a/plug-ins/shape/shape-export.c
+++ b/plug-ins/shape/shape-export.c
@@ -22,13 +22,6 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  */
-/*
- * TODO:
- *   - While porting to use DiaSvgRenderer I removed all connection point
-       adding to fill_* methods with the assumption that they always have
-       a corresponding draw_* method call where the connection points are 
-       already added. Correct me if I'm wrong ...                    --hb 
- */
 #include <config.h>
 
 #include <stdlib.h>
@@ -74,7 +67,12 @@ typedef struct _ShapeRenderer ShapeRenderer;
 typedef struct _ShapeRendererClass ShapeRendererClass;
 
 /*!
- * \brief Shape export for use as \ref Shapes
+ * \brief Shape export for use as new _Custom object
+ *
+ * Render to the SVG Shape dialect including connection points and icon information.
+ * The SVG output is unscaled - that is with untransformed diagram coordinates.
+ *
+ * \sa Shapes
  *
  * \extends _DiaSvgRenderer
  */
@@ -136,6 +134,11 @@ static void add_ellipse_connection_points(ShapeRenderer *renderer,
 /* Moved to reduce confusion of Doxygen */
 GType shape_renderer_get_type (void) G_GNUC_CONST;
 
+/*!
+ * \brief Create a shape renderer and initialize it from the diagram
+ *
+ * \relates _DiaSvgRenderer
+ */
 static DiaSvgRenderer *
 new_shape_renderer(DiagramData *data, const char *filename)
 {
@@ -260,7 +263,15 @@ shape_renderer_class_init (ShapeRendererClass *klass)
 }
 
 /* member implementations */
-/* full overwrite */
+/*!
+ * \brief Render an object
+ *
+ * Most objects rendering is delegated to the base class. Only special
+ * objects representing connection points are not rendered, but instead
+ * translated into shape connection points.
+ *
+ * \memberof _ShapeRenderer
+ */
 static void 
 draw_object(DiaRenderer *self,
             DiaObject   *object,
@@ -283,6 +294,10 @@ draw_object(DiaRenderer *self,
   }
 }
 
+/*!
+ * \brief Save the shape file
+ * \memberof _ShapeRenderer
+ */
 static void
 end_render(DiaRenderer *self)
 {
@@ -298,6 +313,10 @@ end_render(DiaRenderer *self)
   xmlFreeDoc(renderer->doc);
 }
 
+/*!
+ * \brief Add a connection point to the shape
+ * \protected \memberof _ShapeRenderer
+ */
 static void
 add_connection_point (ShapeRenderer *renderer, 
                       Point *point, gboolean design_connection, 
@@ -346,6 +365,10 @@ add_connection_point (ShapeRenderer *renderer,
   
 }
 
+/*!
+ * \brief Draw a line and add three connection points
+ * \memberof _ShapeRenderer
+ */
 static void
 draw_line(DiaRenderer *self, 
          Point *start, Point *end, 
@@ -366,7 +389,12 @@ draw_line(DiaRenderer *self,
 
 }
 
-/* complete overwrite, code duplication with base class */
+/*!
+ * \brief Draw a polyline and add connection points
+ *
+ * \note Complete overwrite, code duplication with base class
+ * \memberof _ShapeRenderer
+ */
 static void
 draw_polyline(DiaRenderer *self, 
              Point *points, int num_points, 
@@ -402,7 +430,12 @@ draw_polyline(DiaRenderer *self,
 }
 
 
-/* complete overwrite, necessary code duplication */
+/*!
+ * \brief Add a polygon including it's connection points
+ *
+ * \note complete overwrite, necessary code duplication?
+ * \memberof _ShapeRenderer
+ */
 static void
 draw_polygon(DiaRenderer *self, 
              Point *points, int num_points, 
@@ -437,6 +470,11 @@ draw_polygon(DiaRenderer *self,
   g_string_free(str, TRUE);
 }
 
+/*!
+ * \brief Add nine connection points for a rectangle
+ *
+ * \protected \memberof _ShapeRenderer
+ */
 static void
 add_rectangle_connection_points (ShapeRenderer *renderer,
                                  Point *ul_corner, Point *lr_corner, real r) 
@@ -479,8 +517,12 @@ add_rectangle_connection_points (ShapeRenderer *renderer,
   pos.y = (ul_corner->y + lr_corner->y)/2;
   add_connection_point(renderer, &pos, FALSE, FALSE);
 }
-    
 
+/*!
+ * \brief Draw a rectangle, if stroked with connection points
+ *
+ * \memberof _ShapeRenderer
+ */
 static void
 draw_rect (DiaRenderer *self, 
            Point *ul_corner, Point *lr_corner,
@@ -495,6 +537,11 @@ draw_rect (DiaRenderer *self,
     add_rectangle_connection_points(renderer, ul_corner, lr_corner, 0.0);
 }
 
+/*!
+ * \brief Draw a rounded rectangle, if stroked with connection points
+ *
+ * \memberof _ShapeRenderer
+ */
 static void
 draw_rounded_rect (DiaRenderer *self, 
                   Point *ul_corner, Point *lr_corner,
@@ -509,6 +556,11 @@ draw_rounded_rect (DiaRenderer *self,
     add_rectangle_connection_points(renderer, ul_corner, lr_corner, rounding);
 }
 
+/*!
+ * \brief Add connection points for an ellipse
+ *
+ * \protected \memberof _ShapeRenderer
+ */
 static void 
 add_ellipse_connection_points (ShapeRenderer *renderer,
                                Point *center, 
@@ -529,6 +581,11 @@ add_ellipse_connection_points (ShapeRenderer *renderer,
   add_connection_point(renderer, &connection, FALSE, FALSE);
 }
 
+/*!
+ * \brief Draw an ellipse, if stroked with connection points
+ *
+ * \memberof _ShapeRenderer
+ */
 static void
 draw_ellipse(DiaRenderer *self, 
              Point *center,
diff --git a/plug-ins/svg/render_svg.c b/plug-ins/svg/render_svg.c
index efbda1e..57b693d 100644
--- a/plug-ins/svg/render_svg.c
+++ b/plug-ins/svg/render_svg.c
@@ -71,8 +71,12 @@ typedef struct _SvgRendererClass SvgRendererClass;
 
 /*!
  * \brief Renderer for SVG export
+ *
+ * This renderer is used for SVG export. It extends the base class with
+ * special handling of multi-line text, grouping of object rendering into
+ * object specific groups and grouping of layers.
+ *
  * \extends _DiaSvgRenderer
- * \bug Doxygen chokes on this file and simply ignores dox after parents
  */
 struct _SvgRenderer
 {
@@ -167,13 +171,14 @@ end_render (DiaRenderer *self)
 }
 
 /*!
- * \brief Advertize special capabilities
+ * \brief Advertise special capabilities
  *
- * Some objects drawing adapts to capabilities advertized by the respective
+ * Some objects drawing adapts to capabilities advertised by the respective
  * renderer. Usually there is a fallback, but generally the real thing should
- * be better.
+ * be better. The SVG renderer preserves holes, transparency, handles affine
+ * transformation and also gradients.
  *
- * \memberof SvgRenderer
+ * \memberof _SvgRenderer
  */
 static gboolean 
 is_capable_to (DiaRenderer *renderer, RenderCapability cap)
@@ -227,7 +232,7 @@ svg_renderer_class_init (SvgRendererClass *klass)
  * different parameters. Here we want to be as compatible as feasible
  * with the SVG specification to support proper diagram exchange.
  *
- * \memberof SvgRenderer
+ * \relates _SvgRenderer
  */
 static DiaSvgRenderer *
 new_svg_renderer(DiagramData *data, const char *filename)
@@ -280,7 +285,7 @@ new_svg_renderer(DiagramData *data, const char *filename)
  * This method intercepts DiaRenderer::draw_layer() to wrap every layer's
  * object into their own named group. This seems to be the common way to
  * transport layer information via SVG.
- * \memberof SvgRenderer
+ * \memberof _SvgRenderer
  */
 static void
 draw_layer (DiaRenderer *self,
@@ -311,7 +316,7 @@ draw_layer (DiaRenderer *self,
  * We could try to be smart and count the objects we using for the object.
  * If it is only one the grouping is superfluous and should be removed.
  *
- * \memberof SvgRenderer
+ * \memberof _SvgRenderer
  */
 static void 
 draw_object(DiaRenderer *self,
@@ -437,7 +442,7 @@ _adjust_space_preserve (xmlNodePtr node,
  * This is the only function in the renderer interface using the
  * font passed in by set_font() method.
  *
- * \memberof SvgRenderer
+ * \memberof _SvgRenderer
  */
 static void
 draw_string(DiaRenderer *self,
@@ -462,7 +467,7 @@ draw_string(DiaRenderer *self,
 
 /*!
  * \brief Support rendering of the _TextLine object
- * \memberof SvgRenderer
+ * \memberof _SvgRenderer
  */
 static void
 draw_text_line(DiaRenderer *self, TextLine *text_line,
@@ -493,10 +498,10 @@ draw_text_line(DiaRenderer *self, TextLine *text_line,
  * \brief multi-line text creation
  *
  * The most high-level member function for text support. Still the
- * others have to be implemented because some _DiaObject dimplementations
+ * others have to be implemented because some _DiaObject implementations
  * use the more low-level variants.
  *
- * \memberof SvgRenderer
+ * \memberof _SvgRenderer
  */
 static void
 draw_text (DiaRenderer *self, Text *text)