[dia] [dox] Some documentation for plug-ins/(layout|python|shape|svg)

From: Hans Breuer <hans src gnome org>
To: commits-list gnome org
Cc:
Subject: [dia] [dox] Some documentation for plug-ins/(layout|python|shape|svg)
Date: Sun, 9 Sep 2012 11:09:34 +0000 (UTC)
commit 98b5344f59b6a9467d94685a84fe4820b480e94d
Author: Hans Breuer <hans breuer org>
Date:   Sun Sep 9 12:40:40 2012 +0200

    [dox] Some documentation for plug-ins/(layout|python|shape|svg)
    
    Using the same names e.g. \extends _DiaRenderer allows to couple
    some PyDia 'inheritance' with the core objects.

 plug-ins/layout/dia-graph.cpp    |   22 ++++
 plug-ins/layout/layout.cpp       |   12 ++
 plug-ins/layout/ogdf-simple.h    |    2 +-
 plug-ins/python/codegen.py       |   27 ++++--
 plug-ins/python/diasvg.py        |   11 ++-
 plug-ins/python/dot2dia.py       |   23 ++++-
 plug-ins/python/export-render.py |   44 ++++++++
 plug-ins/python/pydia-render.c   |  210 +++++++++++++++++++++++++++++++++++--
 plug-ins/shape/shape-export.c    |   14 ++-
 plug-ins/svg/render_svg.c        |   68 +++++++++++--
 10 files changed, 395 insertions(+), 38 deletions(-)
---
diff --git a/plug-ins/layout/dia-graph.cpp b/plug-ins/layout/dia-graph.cpp
index d6f061d..45b2a62 100644
--- a/plug-ins/layout/dia-graph.cpp
+++ b/plug-ins/layout/dia-graph.cpp
@@ -28,6 +28,10 @@
 #include <stdio.h>
 #include <vector>
 
+/*!
+ * \brief A simple x,y coodinate
+ * \ingroup LayoutPlugin
+ */
 struct Point
 {
   double x;
@@ -35,6 +39,10 @@ struct Point
   Point (double _x, double _y) : x(_x), y(_y) {}
 };
 
+/*!
+ * \brief Another node representation
+ * \ingroup LayoutPlugin
+ */
 struct Node
 {
   Point center;
@@ -44,9 +52,18 @@ struct Node
 };
 
 typedef std::vector<Node> Nodes;
+/*!
+ * \brief The Edge object is just stroing bends here
+ * \ingroup LayoutPlugin
+ */
 typedef std::vector<Point> Edge;
 typedef std::vector<Edge> Edges;
 
+/*!
+ * \brief Implementing the IGraph interface for simple layout algorithms
+ *
+ * \ingroup LayoutPlugin
+ */
 class DiaGraph : public IGraph
 {
 public :
@@ -93,6 +110,11 @@ DiaGraph::AddEdge (int srcNode, int destNode, double* points, int len)
   return pos;
 }
 
+/*!
+ * \brief Invoke the given layout algoritm
+ *
+ * \ingroup LayoutPlugin
+ */
 IGraph::eResult
 DiaGraph::Layout (const char *module)
 {
diff --git a/plug-ins/layout/layout.cpp b/plug-ins/layout/layout.cpp
index 3ae6566..9faf942 100644
--- a/plug-ins/layout/layout.cpp
+++ b/plug-ins/layout/layout.cpp
@@ -18,6 +18,14 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  */
+ 
+/*!
+ * \file layout.cpp - plugin for automatic diagram layout
+ */
+/*!
+ * \defgroup LayoutPlugin
+ * \ingroup Plugins
+ */
 #include <config.h>
 
 #include "intl.h"
@@ -188,6 +196,10 @@ _obj_set_bends (DiaObject *obj, std::vector<double>& coords)
 
 typedef IGraph *(*GraphCreateFunc)();
 
+/*!
+ * \brief Calback function invoking layout algorithms from Dia's menu
+ * \ingroup LayoutPlugin
+ */
 static ObjectChange *
 layout_callback (DiagramData *data,
                  const gchar *filename,
diff --git a/plug-ins/layout/ogdf-simple.h b/plug-ins/layout/ogdf-simple.h
index 06dea86..68825cf 100644
--- a/plug-ins/layout/ogdf-simple.h
+++ b/plug-ins/layout/ogdf-simple.h
@@ -25,7 +25,7 @@
  * \brief Abstract graph interface to be fed by Dia
  *
  * This interface must not expose any allocation/deallocations and it shall
- * not let pass any exceptions, because the consumer probaly can't catch them. 
+ * not let pass any exceptions, because the consumer probaly can't catch them.
  */
 class IGraph
 {
diff --git a/plug-ins/python/codegen.py b/plug-ins/python/codegen.py
index 60b4ed5..04c55c7 100644
--- a/plug-ins/python/codegen.py
+++ b/plug-ins/python/codegen.py
@@ -41,6 +41,10 @@ class Klass :
 	def SetInheritance_type(self, inheritance_type):
 		self.inheritance_type = inheritance_type
 
+##
+# \brief Base class of all the code generators
+# \extends _DiaPyRenderer
+# \ingroup PyDia
 class ObjRenderer :
 	"Implements the Object Renderer Interface and transforms diagram into its internal representation"
 	def __init__ (self) :
@@ -115,6 +119,8 @@ class ObjRenderer :
 		self.attributes = []
 		self.operations = []
 
+##
+# \brief Generate a Python source file from an UML class diagram
 class PyRenderer(ObjRenderer) : 
 	def __init__(self) :
 		ObjRenderer.__init__(self)
@@ -147,6 +153,8 @@ class PyRenderer(ObjRenderer) :
 		f.close()
 		ObjRenderer.end_render(self)
 
+##
+# \brief Generate C++ source files from an UML class diagram
 class CxxRenderer(ObjRenderer) :
 	def __init__(self) :
 		ObjRenderer.__init__(self)
@@ -210,7 +218,7 @@ class CxxRenderer(ObjRenderer) :
 		f.close()
 		ObjRenderer.end_render(self)
 
-# #############################################################################
+##
 # JsRenderer: export Dia UML diagram to Object style ECMA5 javascript code.
 #
 # Features:
@@ -279,7 +287,7 @@ class JsRenderer(ObjRenderer) :
 		f.close()
 		ObjRenderer.end_render(self)
 
-# #############################################################################
+##
 # PascalRenderer: export Dia UML diagram to Object Pascal (Free Pascal, Delphi)
 #
 # Please follow some "drawing guidelines" and "naming conventions" so that the
@@ -337,7 +345,6 @@ class JsRenderer(ObjRenderer) :
 #     - no "Attributes" for interface definitions, but properties are
 #       allowed
 #     - default values for method parameters must be the last parameters
-
 class PascalRenderer(ObjRenderer) :
 	def __init__(self) :
 		ObjRenderer.__init__(self)
@@ -456,28 +463,28 @@ class PascalRenderer(ObjRenderer) :
 		f.close()
 		ObjRenderer.end_render(self)
 
-# ######################################################################
+##
 # JavaRenderer: export Dia UML diagram to Java
+#
 # improved by: Manuel Arguelles
 #
 # Features:
 #	* Comments for classes, attributes, methods and methods parameters are
 #	  supported. Uses a comment style javaDoc-like. The comments are
-#     divided into lines if they exceed 79 characters.
+#	  divided into lines if they exceed 79 characters.
 #	* Splits the classes in separate files. Creates a file that contains
 #	  the dia/codegen.py firm :)
 #
 # Fixes:
 #	* Visibilities "private" and "protected" were reversed.
-#   * Comments for classes, attributes, methods and methods parameters.
+#	* Comments for classes, attributes, methods and methods parameters.
 #	* Comments are divided into lines if they exceed 79 characters.
 #	* Splits the classes in separate files.
 #	* Not write "NULL" in empty comments.
 #	* Writes the default values of the arguments of the methods.
 #	* Makes public all the classes and interfaces.
 #	* Not write "static" in all the methods.
-# ######################################################################
-
+#
 class JavaRenderer(ObjRenderer) :
 	def __init__(self) :
 		ObjRenderer.__init__(self)
@@ -487,7 +494,6 @@ class JavaRenderer(ObjRenderer) :
 
 		mainfile = open(self.filename, "w")
 		mainfile.write("/* Generated by dia/codegen.py\n *\n * Generated files:\n")
-		#mainfile.close()
 		for name, klass in self.klasses.iteritems() :
 			# splits the classes in separate files
 			classfile = self.filename[:self.filename.rfind("/")+1] + name.capitalize() + ".java"
@@ -585,8 +591,11 @@ class JavaRenderer(ObjRenderer) :
 		mainfile.close()
 		ObjRenderer.end_render(self)
 
+##
 # PhpRenderer: export Dia UML diagram to PHP
+#
 # Added by: Steven Garcia
+#
 # This is similar to the Java renderer except for PHP
 # Added class scope (static) support
 class PhpRenderer(ObjRenderer) :
diff --git a/plug-ins/python/diasvg.py b/plug-ins/python/diasvg.py
index c4f90eb..af63730 100644
--- a/plug-ins/python/diasvg.py
+++ b/plug-ins/python/diasvg.py
@@ -1,8 +1,6 @@
 #  PyDia SVG Renderer
 #  Copyright (c) 2003, 2004 Hans Breuer <hans breuer org>
 #
-#  A full blown SVG(Z) renderer. As of this writing less bugs in the output
-#  than the Dia SVG renderer written in C
 
 #    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
@@ -20,6 +18,15 @@
 
 import sys, string, dia
 
+##
+# \brief The second SvgRenderer implemntation for Dia
+#
+# A full blown SVG(Z) renderer. As of the initial writing less bugs in the output
+# than the Dia SVG renderer written in C. Nowadays the _SvgRenderer is on par,
+# but this one is still easier to extend and experiment with.
+#
+# \extends _DiaPyRenderer
+# \ingroup ExportFilters
 class SvgRenderer :
 	def __init__ (self) :
 		self.f = None
diff --git a/plug-ins/python/dot2dia.py b/plug-ins/python/dot2dia.py
index 3de3840..7b4a860 100644
--- a/plug-ins/python/dot2dia.py
+++ b/plug-ins/python/dot2dia.py
@@ -15,7 +15,10 @@
 #   along with this program; if not, write to the Free Software
 #   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 
-# translate dot ( http://www.graphviz.org/ ) to Dia format
+##
+# \file dot2dia.py \brief translate dot ( http://www.graphviz.org/ ) to Dia format
+# \ingroup ImportFilters
+
 import re, string, sys
 
 # FIXME: keywords are case indepentend
@@ -47,6 +50,8 @@ def DictFromString (s) :
 			d[m.group ("key")] = StripQuotes(m.group ("val"))
 	return d
 
+##
+# \brief Accumulating information with _DiaObject
 class Object :
 	""" will end as a Dia Object """
 	def __init__ (self, typename, parms) :
@@ -57,7 +62,8 @@ class Object :
 			return float(self.parms['fontsize']) * cmPoints
 		except :
 			return 0.6
-
+##
+# \brief The nodes of the graph - finally represented as _Ellipse
 class Node(Object) :
 	def __init__ (self, name, parms) :
 		Object.__init__(self, "Standard - Ellipse", parms)
@@ -82,6 +88,8 @@ class Node(Object) :
 			print "No size on '%s'" % (self.name,)
 		return w,h
 
+##
+# \brief The edges of the graph - finally represented as _Bezierline
 class Edge(Object) :
 	def __init__ (self, src, dest, parms) :
 		Object.__init__(self, "Standard - BezierLine", parms)
@@ -140,6 +148,8 @@ def MergeParms (d, extra) :
 		if not d.has_key(k) :
 			d[k] = extra[k]
 
+##
+# \brief Parsing the given dot file
 def Parse(sFile) :
 	f = open(sFile, 'r')
 	s = f.read()
@@ -179,6 +189,13 @@ def Parse(sFile) :
 			edges.append(Edge(StripQuotes(m.group("n1")), StripQuotes(m.group("n2")), DictFromString(m.group("dict"))))
 	return [nodes, edges]
 
+##
+# \brief Adding a label for the edges
+# 
+# This function could be improved if Dia would allow to
+# attach labels to arbitrary objects. For the time being
+# only the initial postion does match, but relayouting the
+# graph in Dia will loose the position
 def AddLabel (layer, pos, label, fontsize, center=0) :
 	""" create a Text object an put it into the layer """
 	textType = dia.get_object_type("Standard - Text")
@@ -191,6 +208,8 @@ def AddLabel (layer, pos, label, fontsize, center=0) :
 		obj.properties["text_vert_alignment"] = 2
 	layer.add_object(obj)
 
+##
+# \brief Callback registered for the ImportFilter
 def ImportFile (sFile, diagramData) :
 	""" read the dot file and create diagram objects """
 	nodes, edges = Parse(sFile)
diff --git a/plug-ins/python/export-render.py b/plug-ins/python/export-render.py
index 9564b07..822579d 100644
--- a/plug-ins/python/export-render.py
+++ b/plug-ins/python/export-render.py
@@ -2,9 +2,19 @@ import sys, dia
 
 # sys.path.insert(0, 'd:/graph/dia/dia')
 
+##
+# \brief A simple example renderer implemented in Python
+# \extends _DiaPyRenderer
+# \ingroup PyDia
 class DumpRenderer :
+	## \brief Constructor
 	def __init__ (self) :
 		pass
+	## \brief Start rendering
+	# For non-interactive renderers it is guaranteed that this function is
+	# called before every drawing function. It should be used to clear the
+	# state from previous use, because the renderer class gets only created
+	# once per Dia session
 	def begin_render (self, data, filename) :
 		# DiagramData
 		self.f = open(filename, "w")
@@ -15,70 +25,104 @@ class DumpRenderer :
 		#self.f.write("grid .width: " + str(data.grid.width) \
 		#			+ " .height" + str(data.grid.height) \
 		#			+ "visible: " + str(data.visible) + "\n")
+	## \brief End rendering
+	# For non-interactive renderers it is guaranteed that all drawing
+	# is finished with this call
 	def end_render (self) :
 		self.f.close()
+	## \brief Remember the line width
 	def set_linewidth (self, width) :
 		self.line_width = width
+	## \brief Remember the line caps
 	def set_linecaps (self, mode) :
 		self.line_caps = mode
+	## \brief Remember the line join
 	def set_linejoin (self, mode) :
 		self.line_join = mode
+	## \brief Remember the line style
 	def set_linestyle (self, style) :
 		self.line_style = style
+	## \brief Remember the dash length
 	def set_dashlength (self, length) :
 		self.dash_length = length
+	## \brief Remember the fill style
 	def set_fillstyle (self, style) :
 		self.fill_style = style
+	## \brief Remember the font
 	def set_font (self, font, size) :
 		self.font = font
+	## \brief Draw a straight line from start to end with color
+	# @param start A point in diagram coordinate system
+	# @param end A point in diagram coordinate system
+	# @param color The color to use for the line
+	# The addtional paramters needed for the drawing are given
+	# by one of the set_*() function above
 	def draw_line (self, start, end, color) :
 		self.f.write("draw_line:" + str(start) + str(end) + str(color) + "\n")
+	## \brief Draw a polyline
+	# @param points An array of points in the diagram coordinate system
+	# @param color The color to use for the line
 	def draw_polyline (self, points, color) :
 		self.f.write("draw_polyline: " + str(color) + "\n")
 		for pt in points :
 			self.f.write ("\t" + str(pt) + "\n")
+	## \brief Draw a polygon
+	# @param points An array of points in the diagram coordinate system
+	# @param color The color to use for the line
 	def draw_polygon (self, points, color) :
 		self.f.write("draw_polygon: " + str(color) + "\n")
 		for pt in points :
 			self.f.write ("\t" + str(pt) + "\n")
+	## \brief Fill a polygon
 	def fill_polygon (self, points, color) :
 		self.f.write("fill_polygon: " + str(color) + "\n")
 		for pt in points :
 			self.f.write ("\t" + str(pt) + "\n")
+	## \brief Draw a rectangle
 	def draw_rect (self, rect, color) :
 		self.f.write("draw_rect: " + str(rect) + str(color) + "\n")
+	## \brief Fill a rectangle
 	def fill_rect (self, rect, color) :
 		self.f.write("fill_rect: " + str(rect) + str(color) + "\n")
+	## \brief Draw an arc
 	def draw_arc (self, center, width, height, angle1, angle2, color) :
 		self.f.write("draw_arc: " + str(center) + ";" \
 				+ str(width) + "x" + str(height) + ";" \
 				+ str(angle1) + "," + str(angle2) + ";" + str(color) + "\n")
+	## \brief Fill an arc
 	def fill_arc (self, center, width, height, angle1, angle2, color) :
 		self.f.write("fill_arc: " + str(center) + ";" \
 				+ str(width) + "x" + str(height) + ";" \
 				+ str(angle1) + "," + str(angle2) + ";" + str(color) + "\n")
+	## \brief Draw an ellipse
 	def draw_ellipse (self, center, width, height, color) :
 		self.f.write("draw_ellipse: " + str(center) \
 				+ str(width) + "x" +str(height) + ";" + str(color) + "\n")
+	## \brief Fill an ellipse
 	def fill_ellipse (self, center, width, height, color) :
 		self.f.write("fill_ellipse: " + str(center) \
 				+ str(width) + "x" +str(height) + ";" + str(color) + "\n")
+	## \brief Draw a bezier line
 	def draw_bezier (self, bezpoints, color) :
 		self.f.write("draw_bezier: " + str(color) + "\n")
 		for pt in bezpoints :
 			self.f.write ("\t" + str(pt) + "\n")
+	## \brief Fill a bezier shape
 	def fill_bezier (self, bezpoints, color) :
 		self.f.write("fill_bezier: " + str(color) + "\n")
 		for pt in bezpoints :
 			self.f.write ("\t" + str(pt) + "\n")
+	## \brief Draw a string
 	def draw_string (self, text, pos, alignment, color) :
 		self.f.write("draw_string: [" + text + "]; " + str(pos) \
 				+ str(alignment) + "; " +str(color))
+	## \brief Draw an image
 	def draw_image (self, point, width, height, image) :
 		self.f.write("draw_image: " + str(point) + str(width) + "x" +str(height) \
 				+ " " + image.filename + "\n")
 		self.f.write("<rgb_data>" + image.rgb_data + "</rgb_data>")
 		self.f.write("<mask_data>" + image.mask_data + "</mask_data>")
 
+## \brief Register the renderer with Dia's export system
 # dia-python keeps a reference to the renderer class and uses it on demand
 dia.register_export ("PyDia Render Export", "diapyr", DumpRenderer())
diff --git a/plug-ins/python/pydia-render.c b/plug-ins/python/pydia-render.c
index 5141a7a..7001d7d 100644
--- a/plug-ins/python/pydia-render.c
+++ b/plug-ins/python/pydia-render.c
@@ -17,6 +17,16 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
+/*!
+ * \file pydia-render.c Wrapper to implement _DiaRenderer in Python
+ *
+ * The PyDiaRenderer is currently defined in Python only. The
+ * DiaPyRenderer is using it's interface to map the gobject
+ * DiaRenderer to it. A next step could be to let Python code
+ * directly inherit from DiaPyRenderer.
+ * To do that probably some code from pygtk.gobject needs to
+ * be borrowed/shared
+ */
 #include <config.h>
 
 #include <Python.h>
@@ -38,14 +48,6 @@
 #include "pydia-error.h"
 #include "pydia-render.h"
 
-/*
- * The PyDiaRenderer is currently defined in Python only. The
- * DiaPyRenderer is using it's interface to map the gobject
- * DiaRenderer to it. A next step could be to let Python code
- * directly inherit from DiaPyRenderer.
- * To do that probably some code from pygtk.gobject needs to
- * be borrowed/shared
- */
 #include "diarenderer.h"
 
 #define DIA_TYPE_PY_RENDERER           (dia_py_renderer_get_type ())
@@ -54,11 +56,23 @@
 #define DIA_IS_PY_RENDERER(obj)        (G_TYPE_CHECK_INSTANCE_TYPE ((obj), DIA_TYPE_PY_RENDERER))
 #define DIA_PY_RENDERER_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), DIA_TYPE_PY_RENDERER, DiaPyRendererClass))
 
-GType dia_py_renderer_get_type (void) G_GNUC_CONST;
-
 typedef struct _DiaPyRenderer DiaPyRenderer;
 typedef struct _DiaPyRendererClass DiaPyRendererClass;
 
+/*!
+ * \brief Wrapper class to allow renderer implementation in Python
+ *
+ * The DiaPyRenderer class serves basically two use cases.
+ * - the assumed to be obvious one is to implement a drawing exporter
+ *   in Python. See diasvg.SvgRenderer for an example.
+ * - the other use case is implemented with codegen.ObjRenderer
+ *   which does not deal with graphical information at all, but instead
+ *   takes the _DiagramData object given in begin_render() and iterates
+ *   over layers and objects to extract textual information.
+ *
+ * \extends _DiaRenderer
+ * \ingroup PyDia
+ */
 struct _DiaPyRenderer
 {
   DiaRenderer parent_instance;
@@ -77,8 +91,20 @@ struct _DiaPyRendererClass
 #define PYDIA_RENDERER(renderer) \
 	(DIA_PY_RENDERER(renderer)->self)
 
-/*
- * Members overwritable by Python scripts
+/* Moved here to avoid Doxygen picking up the wrong definitions */
+GType dia_py_renderer_get_type (void) G_GNUC_CONST;
+
+/*!
+ * \brief Begin rendering with Python
+ *
+ * @param renderer Explicit this pointer
+ * @param update The rectangle to update or NULL for everything
+ *
+ * The Python side of the begin_render() method has a different signature.
+ * It gets passed in a PyDia wrapped _DiagramData object and a filename
+ * to store to.
+ *
+ * \memberof _DiaPyRenderer
  */
 static void
 begin_render(DiaRenderer *renderer, const Rectangle *update)
@@ -104,6 +130,11 @@ begin_render(DiaRenderer *renderer, const Rectangle *update)
   }
 }
 
+/*!
+ * \brief Finalize drawing/exporting
+ *
+ * \memberof _DiaPyRenderer
+ */
 static void
 end_render(DiaRenderer *renderer)
 {
@@ -126,6 +157,13 @@ end_render(DiaRenderer *renderer)
   setlocale(LC_NUMERIC, DIA_PY_RENDERER(renderer)->old_locale);
 }
 
+/*!
+ * \brief Set linewidth for later use
+ *
+ * Optional on the PyDia side.
+ *
+ * \memberof _DiaPyRenderer
+ */
 static void
 set_linewidth(DiaRenderer *renderer, real linewidth)
 {  
@@ -148,6 +186,13 @@ set_linewidth(DiaRenderer *renderer, real linewidth)
     PyErr_Clear();
 }
 
+/*!
+ * \brief Set linecaps for later use
+ *
+ * Optional on the PyDia side.
+ *
+ * \memberof _DiaPyRenderer
+ */
 static void
 set_linecaps(DiaRenderer *renderer, LineCaps mode)
 {
@@ -181,6 +226,13 @@ set_linecaps(DiaRenderer *renderer, LineCaps mode)
     PyErr_Clear();
 }
 
+/*!
+ * \brief Set linejoin for later use
+ *
+ * Optional on the PyDia side.
+ *
+ * \memberof _DiaPyRenderer
+ */
 static void
 set_linejoin(DiaRenderer *renderer, LineJoin mode)
 {
@@ -214,6 +266,13 @@ set_linejoin(DiaRenderer *renderer, LineJoin mode)
     PyErr_Clear();
 }
 
+/*!
+ * \brief Set linestyle for later use
+ *
+ * Optional on the PyDia side.
+ *
+ * \memberof _DiaPyRenderer
+ */
 static void
 set_linestyle(DiaRenderer *renderer, LineStyle mode)
 {
@@ -252,6 +311,13 @@ set_linestyle(DiaRenderer *renderer, LineStyle mode)
     PyErr_Clear();
 }
 
+/*!
+ * \brief Set dash length for later use
+ *
+ * Optional on the PyDia side.
+ *
+ * \memberof _DiaPyRenderer
+ */
 static void
 set_dashlength(DiaRenderer *renderer, real length)
 {  
@@ -274,6 +340,13 @@ set_dashlength(DiaRenderer *renderer, real length)
     PyErr_Clear();
 }
 
+/*!
+ * \brief Set fillstyle for later use
+ *
+ * Optional on the PyDia side.
+ *
+ * \memberof _DiaPyRenderer
+ */
 static void
 set_fillstyle(DiaRenderer *renderer, FillStyle mode)
 {
@@ -303,6 +376,13 @@ set_fillstyle(DiaRenderer *renderer, FillStyle mode)
     PyErr_Clear();
 }
 
+/*!
+ * \brief Set font for later use
+ *
+ * Optional on the PyDia side.
+ *
+ * \memberof _DiaPyRenderer
+ */
 static void
 set_font(DiaRenderer *renderer, DiaFont *font, real height)
 {
@@ -330,6 +410,34 @@ set_font(DiaRenderer *renderer, DiaFont *font, real height)
 
 static gpointer parent_class = NULL;
 
+/*!
+ * \brief Draw object
+ *
+ * Optional on the PyDia side. If not implemented the base class method
+ * will be called.
+ *
+ * Intercepting this method on the Python side allows to create per 
+ * object information in the drawing. It is also necessary if the PyDia 
+ * renderer should support transformations.
+ *
+ * If implementing a drawing exposrt filter and overwriting draw_object()
+ * the following code shall be used. Otherwise no draw/fill method will
+ * be called at all.
+ *
+ * \code
+	# don't forget to render the object
+	object.draw (self)
+ * \endcode
+ *
+ * Not calling the object draw method is only usefull when a non-drawing
+ * export - e.g. code generation \sa codegen.py - is implemented.
+ *
+ * @param renderer Self
+ * @param object The object to draw
+ * @param matrix The transformation matrix to use or NULL for no transformation
+ *
+ * \memberof _DiaPyRenderer
+ */
 static void
 draw_object (DiaRenderer *renderer, DiaObject *object, DiaMatrix *matrix)
 {
@@ -365,6 +473,14 @@ draw_object (DiaRenderer *renderer, DiaObject *object, DiaMatrix *matrix)
   }
 }
 
+/*!
+ * \brief Draw line
+ *
+ * Not optional on the PyDia side. If not implemented a runtime warning 
+ * will be generated when called.
+ *
+ * \memberof _DiaPyRenderer
+ */
 static void
 draw_line(DiaRenderer *renderer, 
           Point *start, Point *end, 
@@ -401,6 +517,13 @@ draw_line(DiaRenderer *renderer,
   }
 }
 
+/*!
+ * \brief Draw polyline
+ *
+ * Optional on the PyDia side. If not implemented fallback to base class member.
+ *
+ * \memberof _DiaPyRenderer
+ */
 static void
 draw_polyline(DiaRenderer *renderer, 
 	      Point *points, int num_points, 
@@ -433,6 +556,13 @@ draw_polyline(DiaRenderer *renderer,
   }
 }
 
+/*!
+ * \brief Draw polygon
+ *
+ * Optional on the PyDia side. If not implemented fallback to base class member.
+ *
+ * \memberof _DiaPyRenderer
+ */
 static void
 draw_polygon(DiaRenderer *renderer, 
 	     Point *points, int num_points, 
@@ -465,6 +595,14 @@ draw_polygon(DiaRenderer *renderer,
   }
 }
 
+/*!
+ * \brief Fill polygon
+ *
+ * Not optional on the PyDia side. If not implemented a runtime warning 
+ * will be generated when called.
+ *
+ * \memberof _DiaPyRenderer
+ */
 static void
 fill_polygon(DiaRenderer *renderer, 
 	     Point *points, int num_points, 
@@ -563,6 +701,14 @@ draw_rounded_rect(DiaRenderer *renderer,
 }
 
 
+/*!
+ * \brief Fill rectangle
+ *
+ * Not optional on the PyDia side. If not implemented a runtime warning 
+ * will be generated when called.
+ *
+ * \memberof _DiaPyRenderer
+ */
 static void
 fill_rect(DiaRenderer *renderer, 
 	  Point *ul_corner, Point *lr_corner,
@@ -667,6 +813,14 @@ draw_arc(DiaRenderer *renderer,
   }
 }
 
+/*!
+ * \brief Fill arc
+ *
+ * Not optional on the PyDia side. If not implemented a runtime warning 
+ * will be generated when called.
+ *
+ * \memberof _DiaPyRenderer
+ */
 static void
 fill_arc(DiaRenderer *renderer, 
 	 Point *center,
@@ -705,6 +859,14 @@ fill_arc(DiaRenderer *renderer,
   }
 }
 
+/*!
+ * \brief Draw ellipse
+ *
+ * Not optional on the PyDia side. If not implemented a runtime warning 
+ * will be generated when called.
+ *
+ * \memberof _DiaPyRenderer
+ */
 static void
 draw_ellipse(DiaRenderer *renderer, 
 	     Point *center,
@@ -740,6 +902,14 @@ draw_ellipse(DiaRenderer *renderer,
   }
 }
 
+/*!
+ * \brief Fill ellipse
+ *
+ * Not optional on the PyDia side. If not implemented a runtime warning 
+ * will be generated when called.
+ *
+ * \memberof _DiaPyRenderer
+ */
 static void
 fill_ellipse(DiaRenderer *renderer, 
 	     Point *center,
@@ -838,6 +1008,14 @@ fill_bezier(DiaRenderer *renderer,
   }
 }
 
+/*!
+ * \brief Draw string
+ *
+ * Not optional on the PyDia side. If not implemented a runtime warning 
+ * will be generated when called.
+ *
+ * \memberof _DiaPyRenderer
+ */
 static void
 draw_string(DiaRenderer *renderer,
 	    const char *text,
@@ -884,6 +1062,14 @@ draw_string(DiaRenderer *renderer,
   }
 }
 
+/*!
+ * \brief Draw image
+ *
+ * Not optional on the PyDia side. If not implemented a runtime warning 
+ * will be generated when called.
+ *
+ * \memberof _DiaPyRenderer
+ */
 static void
 draw_image(DiaRenderer *renderer,
 	   Point *point,
diff --git a/plug-ins/shape/shape-export.c b/plug-ins/shape/shape-export.c
index e196859..bfa98c4 100644
--- a/plug-ins/shape/shape-export.c
+++ b/plug-ins/shape/shape-export.c
@@ -71,11 +71,14 @@ G_BEGIN_DECLS
 #define SHAPE_IS_RENDERER(obj)        (G_TYPE_CHECK_INSTANCE_TYPE ((obj), SHAPE_TYPE_RENDERER))
 #define SHAPE_RENDERER_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), SHAPE_TYPE_RENDERER, ShapeRendererClass))
 
-GType shape_renderer_get_type (void) G_GNUC_CONST;
-
 typedef struct _ShapeRenderer ShapeRenderer;
 typedef struct _ShapeRendererClass ShapeRendererClass;
 
+/*!
+ * \brief Shape export for use as \ref Shapes
+ *
+ * \extends _DiaSvgRenderer
+ */
 struct _ShapeRenderer
 {
   DiaSvgRenderer parent_instance;
@@ -102,8 +105,8 @@ static void draw_line(DiaRenderer *self,
 		      Color *line_colour);
 static void 
 draw_object(DiaRenderer *self,
-              DiaObject   *object,
-	          DiaMatrix   *matrix);		      
+            DiaObject   *object,
+	    DiaMatrix   *matrix);
 static void draw_polyline(DiaRenderer *self, 
 			  Point *points, int num_points, 
 			  Color *line_colour);
@@ -128,6 +131,9 @@ static void add_ellipse_connection_points(ShapeRenderer *renderer,
                                           Point *center,
                                           real width, real height);      
 
+/* Moved to reduce confusion of Doxygen */
+GType shape_renderer_get_type (void) G_GNUC_CONST;
+
 static DiaSvgRenderer *
 new_shape_renderer(DiagramData *data, const char *filename)
 {
diff --git a/plug-ins/svg/render_svg.c b/plug-ins/svg/render_svg.c
index b7cd25e..45f3e52 100644
--- a/plug-ins/svg/render_svg.c
+++ b/plug-ins/svg/render_svg.c
@@ -55,16 +55,20 @@ G_BEGIN_DECLS
 #define SVG_IS_RENDERER(obj)        (G_TYPE_CHECK_INSTANCE_TYPE ((obj), SVG_TYPE_RENDERER))
 #define SVG_RENDERER_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), SVG_TYPE_RENDERER, SvgRendererClass))
 
-GType svg_renderer_get_type (void) G_GNUC_CONST;
-
 typedef struct _SvgRenderer SvgRenderer;
 typedef struct _SvgRendererClass SvgRendererClass;
 
+/*!
+ * \brief Svg renderer written in C
+ *
+ * \extends _DiaSvgRenderer
+ * \bug Doxygen chokes on this file and simply ignores dox after parents
+ */
 struct _SvgRenderer
 {
   DiaSvgRenderer parent_instance;
   
-  /* track the parents while grouping in draw_object() */
+  /*! track the parents while grouping in draw_object() */
   GQueue *parents;
 };
 
@@ -75,6 +79,9 @@ struct _SvgRendererClass
 
 G_END_DECLS
 
+/* Moved because it disturbs Doxygen */
+GType svg_renderer_get_type (void) G_GNUC_CONST;
+
 static DiaSvgRenderer *new_svg_renderer(DiagramData *data, const char *filename);
 
 static void draw_object       (DiaRenderer *renderer,
@@ -182,7 +189,15 @@ svg_renderer_class_init (SvgRendererClass *klass)
   renderer_class->draw_text_line  = draw_text_line;
 }
 
-
+/*!
+ * \brief Cration and intialization of the SvgRenderer
+ *
+ * Using the same base class as the Shape renderer, but with slightly
+ * different parameters. Here we want to be as compatible as feasible
+ * with the SVG specification to support proper diagram exchage.
+ *
+ * \memberof SvgRenderer
+ */
 static DiaSvgRenderer *
 new_svg_renderer(DiagramData *data, const char *filename)
 {
@@ -234,15 +249,19 @@ new_svg_renderer(DiagramData *data, const char *filename)
   return renderer;
 }
 
+/*!
+ * \brief Wrap every object in \<g\>\</g\> and apply transformation
+ *
+ * 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 ScgRenderer
+ */
 static void 
 draw_object(DiaRenderer *self,
             DiaObject   *object,
 	    DiaMatrix   *matrix)
 {
-  /* wrap in  <g></g> 
-   * 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.
-   */
   DiaSvgRenderer *renderer = DIA_SVG_RENDERER (self);
   SvgRenderer *svg_renderer = SVG_RENDERER (self);
   int n_children = 0;
@@ -278,6 +297,10 @@ draw_object(DiaRenderer *self,
   }
 }
 
+/*!
+ * \brief creation of rectangles with corner radius
+ * \memberof SvgRenderer
+ */
 static void
 draw_rounded_rect(DiaRenderer *self, 
                   Point *ul_corner, Point *lr_corner,
@@ -305,6 +328,10 @@ draw_rounded_rect(DiaRenderer *self,
   xmlSetProp(node, (const xmlChar *)"ry", (xmlChar *) buf);
 }
 
+/*!
+ * \brief creation of filled rectangles with corner radius
+ * \memberof SvgRenderer
+ */
 static void
 fill_rounded_rect(DiaRenderer *self, 
                   Point *ul_corner, Point *lr_corner,
@@ -401,6 +428,14 @@ node_set_text_style (xmlNodePtr      node,
   g_free(style);
 }
 
+/*!
+ * \brief Support rendering of raw text
+ *
+ * This is the only function in the renderer interface using the
+ * font passed in by set_font() method.
+ *
+ * \memberof SvgRenderer
+ */
 static void
 draw_string(DiaRenderer *self,
 	    const char *text,
@@ -421,6 +456,10 @@ draw_string(DiaRenderer *self,
   xmlSetProp(node, (xmlChar *)"y", (xmlChar *)d_buf);
 }
 
+/*!
+ * \brief Support rendering of the _TextLine object
+ * \memberof SvgRenderer
+ */
 static void
 draw_text_line(DiaRenderer *self, TextLine *text_line,
 	       Point *pos, Alignment alignment, Color *colour)
@@ -445,6 +484,15 @@ draw_text_line(DiaRenderer *self, TextLine *text_line,
   xmlSetProp(node, (const xmlChar*)"textLength", (xmlChar *) d_buf);
 }
 
+/*!
+ * \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
+ * use the more low-level variants.
+ *
+ * \memberof SvgRenderer
+ */
 static void
 draw_text (DiaRenderer *self, Text *text)
 {
@@ -477,6 +525,10 @@ draw_text (DiaRenderer *self, Text *text)
   }
 }
 
+/*!
+ * \brief Callback function registered for export
+ * \ingroup ExportFilters
+ */
 static gboolean
 export_svg(DiagramData *data, DiaContext *ctx,
 	   const gchar *filename, const gchar *diafilename,
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]