GNOME.org
 

[dia] dox: improved grouping and \brief descriptions

commit 825ee461f8b2c07f8a9cfe0f3b9c7fa848edb94c
Author: Hans Breuer <hans breuer org>
Date:   Sun Oct 14 15:03:41 2012 +0200

    dox: improved grouping and \brief descriptions
    
    - removed some superfluous \file documentation (or folded them
      into the \brief description)
    - added a few more words to some documentation details
    - added cairo plug-in to generate documentation from
    - doygenification of DiaImage documentation
    - fixed Doxygen build warnings

 lib/Doxyfile                       |    3 +-
 lib/arrows.h                       |    3 +-
 lib/autoroute.c                    |    6 +-
 lib/bezier_conn.h                  |    2 -
 lib/boundingbox.c                  |    2 -
 lib/boundingbox.h                  |    8 +--
 lib/color.c                        |    2 -
 lib/color.h                        |    9 +---
 lib/connection.c                   |    1 -
 lib/connection.h                   |    1 -
 lib/connectionpoint.c              |    2 -
 lib/connectionpoint.h              |    1 +
 lib/dia.dox                        |   55 ++++++++----------
 lib/dia_image.c                    |  110 ++++++++++++++++++++++++++----------
 lib/dia_svg.c                      |    5 +-
 lib/font.h                         |    1 +
 lib/objchange.h                    |    5 +-
 lib/object.c                       |    1 -
 objects/custom/shape_typeinfo.c    |    8 ++-
 objects/standard/standard.c        |    2 +
 plug-ins/cairo/diacairo-renderer.c |   45 +++++++++++----
 plug-ins/cairo/diacairo.h          |   29 +++++++---
 22 files changed, 183 insertions(+), 118 deletions(-)
---
diff --git a/lib/Doxyfile b/lib/Doxyfile
index 93dbec4..22d8b7b 100644
--- a/lib/Doxyfile
+++ b/lib/Doxyfile
@@ -12,7 +12,7 @@ WARN_IF_UNDOCUMENTED   = NO
 WARN_LOGFILE           = doxygen.log
 INPUT                  = ../lib ../objects/standard ../objects/custom \
                          ../plug-ins/python ../plug-ins/svg ../plug-ins/shape \
-                         ../plug-ins/layout
+                         ../plug-ins/cairo ../plug-ins/layout
 #STRIP_FROM_PATH        = ../
 FILE_PATTERNS          = *.c *.h *.dox *.py *.cpp
 # define HAVE_CAIRO to get the Outline dox
@@ -32,6 +32,7 @@ COLLABORATION_GRAPH    = YES
 HIDE_UNDOC_RELATIONS   = YES
 # class graph is just redundant than
 CLASS_GRAPH            = YES
+GROUP_GRAPHS           = NO
 MAX_DOT_GRAPH_DEPTH    = 3
 
 # Needed to e.g. get documentation for standard/arc.c
diff --git a/lib/arrows.h b/lib/arrows.h
index 7429f00..489342f 100644
--- a/lib/arrows.h
+++ b/lib/arrows.h
@@ -28,8 +28,9 @@
 /* NOTE: Add new arrow types at the end, or the enums
    will change order leading to file incompatibilities. */
 /*!
- * \defgroup ObjectArrows Arrows for Connection
+ * \defgroup ObjectArrows Arrows
  * \ingroup ObjectParts
+ * \brief A set of standard arrows to be used at line ends
  */
 
 /*!
diff --git a/lib/autoroute.c b/lib/autoroute.c
index ffc6e4f..b34a2a3 100644
--- a/lib/autoroute.c
+++ b/lib/autoroute.c
@@ -20,11 +20,9 @@
  */
 
 /*!
- * \file autoroute.c - simple autorouting for orthogonal lines
- */
-/*!
  * \defgroup Autorouting Built-in Autorouting
- * \ingroup ObjectServices
+ * \brief Simple autorouting for \ref _OrthConn "orthogonal lines"
+ * \ingroup ObjectParts
  */
 #include "config.h"
 
diff --git a/lib/bezier_conn.h b/lib/bezier_conn.h
index b11c9d1..5d0b9c5 100644
--- a/lib/bezier_conn.h
+++ b/lib/bezier_conn.h
@@ -18,8 +18,6 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  */
  
-/** \file bezier_conn.h Allows to construct object consisting of bezier lines */
-
 #ifndef BEZIER_CONN_H
 #define BEZIER_CONN_H
 
diff --git a/lib/boundingbox.c b/lib/boundingbox.c
index 4308b02..88cbca0 100644
--- a/lib/boundingbox.c
+++ b/lib/boundingbox.c
@@ -17,8 +17,6 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  */
 
-/** \file boundingbox.c This code is nothing but a fancy pile of FPU crap. */
-
 #include <config.h>
 
 #define _BSD_SOURCE 1
diff --git a/lib/boundingbox.h b/lib/boundingbox.h
index 6127fe1..94d78c6 100644
--- a/lib/boundingbox.h
+++ b/lib/boundingbox.h
@@ -17,12 +17,10 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  */
 
-/*! 
- * \file boundingbox.h Boundingbox calculation (helpers)
- */
 /*!
- * \defgroup ObjectBBox Bounding box calculation
- * \ingroup ObjectServices
+ * \defgroup ObjectBBox Bounding box
+ * \brief Calculations considering line width, caps and joins
+ * \ingroup ObjectParts
  */
 
 #ifndef BOUNDINGBOX_H
diff --git a/lib/color.c b/lib/color.c
index 4d23f4a..799b108 100644
--- a/lib/color.c
+++ b/lib/color.c
@@ -16,8 +16,6 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  */
  
-/** \file color.c Diagram and object tinting */
-
 #include <config.h>
 
 #include <stdio.h>
diff --git a/lib/color.h b/lib/color.h
index 5e92f9b..b625369 100644
--- a/lib/color.h
+++ b/lib/color.h
@@ -16,13 +16,6 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  */
 
-/*!
- * \file color.h Diagram and object tinting
- */
-/*!
- * \defgroup ObjectColors Colors for DiaObject
- * \ingroup ObjectParts
- */
 #ifndef COLOR_H
 #define COLOR_H
 
@@ -32,7 +25,7 @@
 
 /*!
  * \brief Dia's internal color representation
- * \ingroup ObjectColors
+ * \ingroup ObjectParts
  */
 struct _Color {
   float red;   /*!< 0..1 */
diff --git a/lib/connection.c b/lib/connection.c
index f6266b8..9b965ca 100644
--- a/lib/connection.c
+++ b/lib/connection.c
@@ -16,7 +16,6 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  */
 
-/*! \file connection.c -- This file handles simple (straight-line) connection basics */
 #include <config.h>
 
 #include <stdio.h>
diff --git a/lib/connection.h b/lib/connection.h
index f320308..bd8dc32 100644
--- a/lib/connection.h
+++ b/lib/connection.h
@@ -16,7 +16,6 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  */
 
-/** \file connection.h -- The basis of connections in Dia */
 #ifndef CONNECTION_H
 #define CONNECTION_H
 
diff --git a/lib/connectionpoint.c b/lib/connectionpoint.c
index 5a1de0d..5ea5b1b 100644
--- a/lib/connectionpoint.c
+++ b/lib/connectionpoint.c
@@ -15,8 +15,6 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  */
- 
-/** \file connectionpoint.c ConnectionPoint implmentation */
 
 #include "config.h"
 #include "connectionpoint.h"
diff --git a/lib/connectionpoint.h b/lib/connectionpoint.h
index e4155c2..2153800 100644
--- a/lib/connectionpoint.h
+++ b/lib/connectionpoint.h
@@ -15,6 +15,7 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  */
+
 /*!
  * \file connectionpoint.h -- Connection Points together with Handles allow to connect objects
  * \ingroup ObjectConnects
diff --git a/lib/dia.dox b/lib/dia.dox
index 420220f..3a0a3db 100644
--- a/lib/dia.dox
+++ b/lib/dia.dox
@@ -22,6 +22,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
 
 There are a bunch of services to help implementing Dia objects.
 
@@ -38,8 +39,9 @@ There are a bunch of services to help implementing Dia objects.
  */
  
 /*!
-\defgroup StdProps Property System for Dia Object
-\ingroup ObjectServices
+\defgroup StdProps Standard Property System
+\ingroup ObjectParts
+\brief Automatic User Interface creation and serialization of object properties
 
 The Propery System for Dia Object allows to 
  - describe type, range and user interface representation, see PropDescription.
@@ -51,19 +53,14 @@ The Propery System for Dia Object allows to
  
 /*!
 \defgroup ObjectParts Building Blocks
-\ingroup Objects
-
+\ingroup Objects Building blocks to help implementing _DiaObject and interfacing _DiaRenderer
+\brief Typical \ref _DiaObject "Objects" are assembled from exisiting building blocks like _DiaImage
 */
 
 /*!
-\defgroup ObjectParts Building Blocks
-\ingroup Objects
-
-*/
-
-/*!
-\defgroup ObjectConnects Connecting Objects
+\defgroup ObjectConnects Object Connections
 \ingroup Objects
+\brief Connections between objects are realized with \ref _Handle "Handle" and \ref _ConnectionPoint "Connection Point"
 
 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 
@@ -80,6 +77,7 @@ and "connected by" (connectionpoint->connected). The former is a 0 or 1 relation
 /*!
 \defgroup Shapes Custom Shape Definition
 \ingroup Objects
+\brief Custom objects can not only be defined by writing C code, but also with a SVG dialect
 
 \verbinclude custom-shapes
 
@@ -88,6 +86,7 @@ and "connected by" (connectionpoint->connected). The former is a 0 or 1 relation
 /*!
 \defgroup ObjectConnects Connecting Objects
 \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 
@@ -102,32 +101,23 @@ and "connected by" (connectionpoint->connected). The former is a 0 or 1 relation
 */
 
 /*!
-\defgroup Shapes Custom Shape Definition
-\ingroup Objects
-
-\verbinclude custom-shapes
-
-*/
-
-/*!
-\defgroup ObjectServices Object Implementation
-\ingroup Objects
- */
-
-/*!
 \defgroup DiagramStructure Diagrams keeping it all together
-\brief A \ref _DiagramData "Diagram" consists of at least one \ref _Layer containing zero or more _DiaObject
+\brief A \ref _DiagramData "Diagram" consists of at least one \ref _Layer "Layer" containing zero or more \ref _DiaObject "Object"
 
  */
 
 /*!
 \defgroup DiagramXmlIo Operations on the XML DOM
+\brief Low level access to the document object model
 \ingroup DiagramStructure
+\details
 \verbinclude diagram.dtd
  */
 
 /*!
 \defgroup Renderers Rendering Objects
+\brief The visual representation of \ref _DiaObject "objects" is done by \ref _DiaRenderer "renderers"
+
 \ingroup Plugins
 
 Dia Objects are drawing themselves to a renderer, be it for display, print or
@@ -138,30 +128,33 @@ to help implementing rendering.
    of high level functions 
  - _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
 
  */
 
 /*!
 \defgroup Plugins Import, Export and other extensions
-
+\brief Extending Dia with optional dependencies 
  */
 
 /*!
-\defgroup ExportFilters Export Filters for various Formats
+\defgroup ExportFilters Export Filters
 \ingroup Plugins
-
+\brief Export filters are usually implmenting the \ref _DiaRenderer "renderer" interface
 
  */
  
 /*!
-\defgroup ImportFilters Import Filters for various Formats
+\defgroup ImportFilters Import Filters
 \ingroup Plugins
-
+\brief Import filters translate an external represenation to Dia \ref _DiaObject "objects"
 
  */
  
 /*!
-\defgroup PyDia Extending Dia with Python
+\defgroup PyDia Scripting Dia
+\brief Extending Dia with Python (http://www.python.org)
+
 \ingroup Plugins
 
 The documentation of PyDia is self-contained with PyDia. You can use some
diff --git a/lib/dia_image.c b/lib/dia_image.c
index 9596de2..22362c3 100644
--- a/lib/dia_image.c
+++ b/lib/dia_image.c
@@ -39,6 +39,18 @@ struct _DiaImageClass {
   GObjectClass parent_class;
 };
 
+/*!
+ * \brief DiaImage is a thin wrapper around GdkPixbuf
+ *
+ * _DiaImage provides some copying accessors as well as internal caching of
+ * a downscaled variant of the underlying pixbuf. Also there is special handling
+ * of 'broken' i.e. typically empty images.
+ *
+ * _DiaImage can be used to assemble _DiaObjects - it is also part of the 
+ * _DiaRenderer interface and thus provides interface to all of the exporters.
+ *
+ * \ingroup ObjectParts
+ */
 struct _DiaImage {
   GObject parent_instance;
   GdkPixbuf *image;
@@ -88,6 +100,10 @@ dia_image_class_init(DiaImageClass* klass)
   object_class->finalize = dia_image_finalize;
 }
 
+/*!
+ * \brief Constructor
+ * \memberof _DiaImage
+ */
 static void 
 dia_image_init_instance(DiaImage *image)
 {
@@ -95,6 +111,10 @@ dia_image_init_instance(DiaImage *image)
   /* zero intialization should be good for us */
 }
 
+/*!
+ * \brief Destructor
+ * \memberof _DiaImage
+ */
 static void
 dia_image_finalize(GObject* object)
 {
@@ -108,8 +128,11 @@ dia_image_finalize(GObject* object)
 
 gboolean _dia_image_initialized = FALSE;
 
-/** Get the image to put in place of a image that cannot be read.
- * @returns A statically allocated image.
+/*!
+ * \brief Constructor of a 'broken' image
+ * Get the image to put in place of a image that cannot be read.
+ * @return A statically allocated image.
+ * \memberof _DiaImage
  */
 DiaImage *
 dia_image_get_broken(void)
@@ -131,10 +154,12 @@ dia_image_get_broken(void)
   return image;
 }
 
-/** Load an image from file.
+/*!
+ * \brief Load an image from file.
  * @param filename Name of the file to load.
- * @returns An image loaded from file, or NULL if an error occurred.
+ * @return An image loaded from file, or NULL if an error occurred.
  *          Error messages will be displayed to the user.
+ * \memberof _DiaImage
  */
 DiaImage *
 dia_image_load(const gchar *filename)
@@ -157,7 +182,6 @@ dia_image_load(const gchar *filename)
 
   dia_img = DIA_IMAGE(g_object_new(DIA_TYPE_IMAGE, NULL));
   dia_img->image = image;
-  /* We have a leak here, unless we add our own refcount */
   dia_img->filename = g_strdup(filename);
 #ifdef SCALING_CACHE
   dia_img->scaled = NULL;
@@ -166,9 +190,12 @@ dia_image_load(const gchar *filename)
 }
 
 /*!
- * Create a Dia Image from in memory GdkPixbuf
+ * \brief Create a Dia Image from in memory GdkPixbuf
  *
  * It stores only a reference, so drop your own after calling this.
+ * Different _DiaImage can share the same underlying pixbuf,
+ * _DiaImage is considered immutable.
+ * \memberof _DiaImage
  */
 DiaImage *
 dia_image_new_from_pixbuf (GdkPixbuf *pixbuf)
@@ -199,13 +226,12 @@ dia_image_unref(DiaImage *image)
   g_object_unref(image);
 }
 
-/** Render an image unto a window.
- * @param image Image object to render.
- * @param window The window to render the image into.
- * @param x X position in window of place to render image.
- * @param y Y position in window of place to render image.
- * @param width Width in pixels of rendering in window.
- * @param height Height in pixels of rendering in window.
+/*!
+ * \brief Create a scaled variant of the underlying pixbuf.
+ * @param image explicit this pointer
+ * @param width Width in pixels of result.
+ * @param height Height in pixels of result.
+ * \memberof _DiaImage
  */
 GdkPixbuf * 
 dia_image_get_scaled_pixbuf(DiaImage *image, int width, int height)
@@ -277,6 +303,12 @@ _guess_format (const gchar *filename)
   return type;
 }
 
+/*!
+ * \brief Save an image under the given filename
+ * If saving was successful the internal filename is updated to the
+ * given one. Otherwise FALSE will be returned.
+ * \memberof _DiaImage
+ */
 gboolean
 dia_image_save(DiaImage *image, const gchar *filename)
 {
@@ -307,9 +339,11 @@ dia_image_save(DiaImage *image, const gchar *filename)
   return saved;
 }
 
-/** Get the width of an image.
+/*!
+ * \brief Get the width of an image.
  * @param image An image object
- * @returns The natural width of the object in pixels.
+ * @return The natural width of the object in pixels.
+ * \memberof _DiaImage
  */
 int 
 dia_image_width(const DiaImage *image)
@@ -318,9 +352,11 @@ dia_image_width(const DiaImage *image)
   return gdk_pixbuf_get_width(image->image);
 }
 
-/** Get the height of an image.
+/*!
+ * \brief Get the height of an image.
  * @param image An image object
- * @returns The natural height of the object in pixels.
+ * @return The natural height of the object in pixels.
+ * \memberof _DiaImage
  */
 int 
 dia_image_height(const DiaImage *image)
@@ -329,9 +365,11 @@ dia_image_height(const DiaImage *image)
   return gdk_pixbuf_get_height(image->image);
 }
 
-/** Get the rowstride number of bytes per row, see gdk_pixbuf_get_rowstride.
+/*!
+ * \brief Get the rowstride number of bytes per row, see gdk_pixbuf_get_rowstride.
  * @param image An image object
- * @returns The rowstride number of the image.
+ * @return The rowstride number of the image.
+ * \memberof _DiaImage
  */
 int
 dia_image_rowstride(const DiaImage *image)
@@ -339,9 +377,11 @@ dia_image_rowstride(const DiaImage *image)
   g_return_val_if_fail (image != NULL, 0);
   return gdk_pixbuf_get_rowstride(image->image);
 }
-/** Direct const access to the underlying GdkPixbuf
+/*! 
+ * \brief Direct const access to the underlying GdkPixbuf
  * @param image An image object
- * @returns The pixbuf
+ * @return The pixbuf
+ * \memberof _DiaImage
  */
 const GdkPixbuf* 
 dia_image_pixbuf (const DiaImage *image)
@@ -351,10 +391,12 @@ dia_image_pixbuf (const DiaImage *image)
   return image->image;
 }
 
-/** Get the raw RGB data from an image.
+/*!
+ * \brief Get the raw RGB data from an image.
  * @param image An image object.
- * @returns An array of bytes (height*rowstride) containing the RGB data
+ * @return An array of bytes (height*rowstride) containing the RGB data
  *          This array should be freed after use.
+ * \memberof _DiaImage
  */
 guint8 *
 dia_image_rgb_data(const DiaImage *image)
@@ -387,10 +429,12 @@ dia_image_rgb_data(const DiaImage *image)
   }
 }
 
-/** Get the mask data for an image.
+/*! 
+ * \brief Get the mask data for an image.
  * @param image An image object.
- * @returns An array of bytes (width*height) with the alpha channel information
- *          from the image.  This array should be freed after use.
+ * @return An array of bytes (width*height) with the alpha channel information
+ *         from the image.  This array should be freed after use.
+ * \memberof _DiaImage
  */
 guint8 *
 dia_image_mask_data(const DiaImage *image)
@@ -419,10 +463,12 @@ dia_image_mask_data(const DiaImage *image)
   return mask;
 }
 
-/** Get full RGBA data from an image.
+/*!
+ * \brief Get full RGBA data from an image.
  * @param image An image object.
- * @returns An array of pixels as delivered by gdk_pixbuf_get_pixels, or
+ * @return An array of pixels as delivered by gdk_pixbuf_get_pixels, or
  *          NULL if the image has no alpha channel.
+ * \memberof _DiaImage
  */
 const guint8 *
 dia_image_rgba_data(const DiaImage *image)
@@ -437,10 +483,12 @@ dia_image_rgba_data(const DiaImage *image)
   }
 }
 
-/** Return the filename associated with an image.
+/*!
+ * \brief Return the filename associated with an image.
  * @param image An image object
- * @returns The filename associated with an image, or "(null)" if the image
- *          has no filename.  This string should *not* be freed by the caller.
+ * @return The filename associated with an image, or "(null)" if the image
+ *         has no filename.  This string should *not* be freed by the caller.
+ * \memberof _DiaImage
  */
 const char *
 dia_image_filename(const DiaImage *image)
diff --git a/lib/dia_svg.c b/lib/dia_svg.c
index 3a429df..8be08d1 100644
--- a/lib/dia_svg.c
+++ b/lib/dia_svg.c
@@ -31,9 +31,10 @@
 #include "dia_svg.h"
 
 /*!
- * \defgroup DiaSvg Services for SVG parsing and generation
+ * \defgroup DiaSvg Services for SVG
  * \ingroup Plugins
- * \brief Services for SVG parsing and generation
+ * \brief A set of function helping to read and write SVG with Dia
+ *
  * The Dia application supports various variants of SVG. There are
  * at least two importers of SVG dialects, namely \ref Shapes and
  * the standard SVG importer \ref Plugins. Both are using theses
diff --git a/lib/font.h b/lib/font.h
index aaf6784..63ebb96 100644
--- a/lib/font.h
+++ b/lib/font.h
@@ -30,6 +30,7 @@
  */
 /*!
  \defgroup ObjectFonts Dia's font definiton
+ \brief Dia's font system based on http://www.pango.org
  \ingroup ObjectParts
  */
 
diff --git a/lib/objchange.h b/lib/objchange.h
index 9573247..7491bbf 100644
--- a/lib/objchange.h
+++ b/lib/objchange.h
@@ -20,8 +20,9 @@
  * \file objchange.h -- Forming the basic of undo support to be implemented in objects 
  */
 /*!
- * \defgroup ObjChange Objects support for undo/redo
- * \ingroup ObjectServices
+ * \defgroup ObjChange Support for undo/redo
+ * \brief Object implmentations need some effort to support undo/redo
+ * \ingroup ObjectParts
  */
 #ifndef OBJCHANGE_H
 #define OBJCHANGE_H
diff --git a/lib/object.c b/lib/object.c
index e006332..2f53fcc 100644
--- a/lib/object.c
+++ b/lib/object.c
@@ -16,7 +16,6 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  */
 
-/** \file lib/object.c implementation of DiaObject related functions */
 #include <config.h>
 
 #include <stdio.h>
diff --git a/objects/custom/shape_typeinfo.c b/objects/custom/shape_typeinfo.c
index c4917d9..6f3d7cd 100644
--- a/objects/custom/shape_typeinfo.c
+++ b/objects/custom/shape_typeinfo.c
@@ -33,14 +33,20 @@
 
 /*!
  * \defgroup ObjectCustom Custom Shapes
+ * \brief Dia plug-in to support custom shapes
+ *
  * \ingroup Shapes
  *
+ * The cusom shape format is supported by a Dia plug-in, too. Disabling
+ * this plug-in will highly reduce the available shape set, but also the
+ * start-up time.
+ *
  * Instead of parsing the complete shape file at start-up we read only
  * the minimal info required to register the type. This should speed
  * up startup a lot and also spare some memory for shapes never used
  * at runtime.
  *
- * There are so many shapes in dia that on my computer there is a difference
+ * There are so many shapes in Dia that on my computer there is a difference
  * of 16MB vs. 36MB total memory consumption with none vs. all of them loaded.
  *
  * The startup time is significantly reduced by the lazy loading via XML SAX, too.
diff --git a/objects/standard/standard.c b/objects/standard/standard.c
index bde0968..ea75b97 100644
--- a/objects/standard/standard.c
+++ b/objects/standard/standard.c
@@ -27,6 +27,8 @@
 
 /*!
 \defgroup StandardObjects Standard Objects
+\brief The minimal set of objects available to Dia
+
 \ingroup Objects
 
 The minimal set of objects available to Dia is defined in the directory objects/standard.
diff --git a/plug-ins/cairo/diacairo-renderer.c b/plug-ins/cairo/diacairo-renderer.c
index 97f800f..279657d 100644
--- a/plug-ins/cairo/diacairo-renderer.c
+++ b/plug-ins/cairo/diacairo-renderer.c
@@ -34,18 +34,6 @@
 #include <pango/pangocairo.h>
 #endif
 
-/*
- * To me the following looks rather suspicious. Why do we need to compile
- * the Cairo plug-in at all if we don't have Cairo? As a result we'll
- * show it in the menus/plugin details and the user expects something
- * although there isn't any functionality behind it. Urgh.
- *
- * With Gtk+-2.7.x cairo must be available so this becomes even more ugly
- * when the user has choosen to not build the diacairo plug-in. If noone
- * can come up with a convincing reason to do it this way I'll probably
- * go back to the dont-build-at-all approach when it breaks the next time.
- *                                                                    --hb 
- */
 #ifdef HAVE_CAIRO
 #  include <cairo.h>
 /* some backend headers, win32 missing in official Cairo */
@@ -198,18 +186,36 @@ end_render(DiaRenderer *self)
   DIAG_STATE(renderer->cr)
 }
 
+/*!
+ * \brief Advertize renderers capabilities
+ *
+ * Especially with cairo this should be 'all' so this function
+ * is complaining if it will return FALSE
+ * \memberof _DiaCairoRenderer
+ */
 static gboolean 
 is_capable_to (DiaRenderer *renderer, RenderCapability cap)
 {
+  static RenderCapability warned = RENDER_HOLES;
+
   if (RENDER_HOLES == cap)
     return TRUE;
   else if (RENDER_ALPHA == cap)
     return TRUE;
   else if (RENDER_AFFINE == cap)
     return TRUE;
+  if (cap != warned)
+    g_warning ("New capability not supported by cairo??");
+  warned = cap;
   return FALSE;
 }
 
+/*!
+ * \brief Render the given object optionally transformed by matrix
+ * @param self explicit this pointer
+ * @param object the _DiaObject to draw
+ * @param matrix the trnsformation matrix to use or NULL
+ */
 static void
 draw_object (DiaRenderer *self, DiaObject *object, DiaMatrix *matrix)
 {
@@ -226,6 +232,13 @@ draw_object (DiaRenderer *self, DiaObject *object, DiaMatrix *matrix)
     cairo_set_matrix (renderer->cr, &before);
 }
 
+/*!
+ * \brief Ensure a minimum of one device unit
+ * Dia as well as many other drawing applications/libraries is using a
+ * line with 0f 0.0 tho mean hairline. Cairo doe not have this capability
+ * so this functions should be used to get the thinnest line possible.
+ * \protected \memberof _DiaCairoRenderer
+ */
 static void
 ensure_minimum_one_device_unit(DiaCairoRenderer *renderer, real *value)
 {
@@ -364,6 +377,14 @@ set_dashlength(DiaRenderer *self, real length)
   set_linestyle(self, renderer->line_style);
 }
 
+/*!
+ * \brief Set the fill style
+ * The fill style is one of the areas, where the cairo library offers a lot
+ * more the Dia currently uses. Cairo can render repeating patterns as well
+ * as linear and radial gradients. As of this writing Dia just uses solid
+ * color fill.
+ * \memberof _DiaCairoRenderer
+ */
 static void
 set_fillstyle(DiaRenderer *self, FillStyle mode)
 {
diff --git a/plug-ins/cairo/diacairo.h b/plug-ins/cairo/diacairo.h
index 65265a6..94e1993 100644
--- a/plug-ins/cairo/diacairo.h
+++ b/plug-ins/cairo/diacairo.h
@@ -52,22 +52,34 @@ GType dia_cairo_renderer_get_type (void) G_GNUC_CONST;
 typedef struct _DiaCairoRenderer DiaCairoRenderer;
 typedef struct _DiaCairoRendererClass DiaCairoRendererClass;
 
+/*!
+ * \brief Multi format renderer based aon cairo API (http://cairographics.org)
+ *
+ * The DiaCairoRenderer supports various output formats depending on the build
+ * configration of libcairo. Typically these include SVG, PNG, PDF, PostScript
+ * and the display of the windowing system in use.
+ * Also - with a recent enough GTK+ version the cairo renderer is interfacing 
+ * the native printing subsystem.
+ * Finally - only on Windows - there is ususally support for Windows Metafiles
+* (WMF and EMF), the latter used for Clipboard transport of the whole diagram.
+ * \extends _DiaRenderer
+ */
 struct _DiaCairoRenderer
 {
-  DiaRenderer parent_instance;
+  DiaRenderer parent_instance; /*!< GObject inheritance */
 
-  cairo_t *cr; /**< if NULL it gest created from the surface */
+  cairo_t *cr; /**< if NULL it gets created from the surface */
   cairo_surface_t *surface; /**< can be NULL to use the provived cr */
- 
+
   double dash_length;
   LineStyle line_style;
-  DiagramData *dia;
+  DiagramData *dia; /*!< pointer to the diagram to render, might be NULL for the display case */
 
   real scale;
-  gboolean with_alpha;
-  gboolean skip_show_page; /**< when using for print avoid the internal show_page */
-  gboolean stroke_pending; /**< to delay call to cairo_stroke */
-  
+  gboolean with_alpha; /*!< define to TRUE for transparent background */
+  gboolean skip_show_page; /*!< when using for print avoid the internal show_page */
+  gboolean stroke_pending; /*!< to delay call to cairo_stroke */
+
   /** caching the font description from set_font */
   PangoLayout *layout;
 };
@@ -81,4 +93,3 @@ struct _DiaCairoRendererClass
 GType dia_cairo_interactive_renderer_get_type (void) G_GNUC_CONST;
 
 G_END_DECLS
-
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]