[dia] [dox] include object/custom in developer documentation

[Hans Breuer <hans src gnome org>]

commit a614038b393cb97aa3a4c620c49a97ab012fde0b
Author: Hans Breuer <hans breuer org>
Date:   Sat Sep 22 16:22:59 2012 +0200

    [dox] include object/custom in developer documentation

 objects/custom/custom_object.c  |   60 +++++++++++++++++----------------------
 objects/custom/shape_info.c     |   26 ++++++++++++++--
 objects/custom/shape_info.h     |   20 +++++++++----
 objects/custom/shape_typeinfo.c |   14 ++++++++-
 4 files changed, 74 insertions(+), 46 deletions(-)
---
diff --git a/objects/custom/custom_object.c b/objects/custom/custom_object.c
index 72a80cb..3ebfd4c 100644
--- a/objects/custom/custom_object.c
+++ b/objects/custom/custom_object.c
@@ -62,26 +62,44 @@ typedef enum {
 
 typedef struct _Custom Custom;
 
+/*!
+ * \brief Custom shape representation as DiaObject
+ *
+ * The custom shape object gets created with varying content given from the
+ * shape file. It currently only spports two different sets of properties,
+ * depending on the use of \code <textbox/> \endcode .
+ *
+ * \extends _Element
+ * \ingroup ObjectCustom
+ */
 struct _Custom {
   Element element;
 
+  /*! ShapeInfo giving the object it's drawing info */
   ShapeInfo *info;
-  /* transformation coords */
+  /*! transformation coords */
   real xscale, yscale;
   real xoffs,  yoffs;
 
-  /* The subscale variables
+  /*!
+   * The subscale variables
    * The old_subscale is used for interactive 
    * (shift-pressed) scaling
+   * @{
    */
   real subscale;
   real old_subscale;
-  /* this is sort of a hack, passing a temporary value
-     using this field, but otherwise 
-     subshapes are going to need major code refactoring: */
+  /*! @} */
+  /*!
+   * \brief Pointer changing during the drawing of the display list
+   * this is sort of a hack, passing a temporary value
+   * using this field, but otherwise 
+   * subshapes are going to need major code refactoring: 
+   */
   GraphicElementSubShape* current_subshape;
-  
+  /*! Connection points need to be dynamically allocated */
   ConnectionPoint *connections;
+  /*! width calculate from line_width */
   real border_width;
   Color border_color;
   Color inner_color;
@@ -98,32 +116,6 @@ struct _Custom {
   TextFitting text_fitting;
 };
 
-typedef struct _CustomProperties {
-  Color *fg_color;
-  Color *bg_color;
-  gboolean show_background;
-  real border_width;
-
-  real padding;
-  DiaFont *font;
-  real font_size;
-  Alignment alignment;
-  Color *font_color;
-} CustomProperties;
-
-
-static CustomProperties default_properties = {
-  NULL,
-  NULL,
-  TRUE, /* show_background */
-  0.0,  /* border_width */
-  0.1, /* pading */
-  NULL, /* no font */
-  0.8, /* it's size */
-  ALIGN_CENTER, /* it's alignment */
-  NULL, /* no font color */
-};
-
 static real custom_distance_from(Custom *custom, Point *point);
 static void custom_select(Custom *custom, Point *clicked_point,
 			  DiaRenderer *interactive_renderer);
@@ -1588,10 +1580,10 @@ custom_create(Point *startpoint,
   custom->border_width = attributes_get_default_linewidth();
   custom->border_color = attributes_get_foreground();
   custom->inner_color = attributes_get_background();
-  custom->show_background = default_properties.show_background;
+  custom->show_background = TRUE;
   attributes_get_default_line_style(&custom->line_style, &custom->dashlength);
 
-  custom->padding = default_properties.padding;
+  custom->padding = 0.1;
 
   custom->flip_h = FALSE;
   custom->flip_v = FALSE;
diff --git a/objects/custom/shape_info.c b/objects/custom/shape_info.c
index bdc0a72..53efb25 100644
--- a/objects/custom/shape_info.c
+++ b/objects/custom/shape_info.c
@@ -97,14 +97,16 @@ shape_info_getbyname(const gchar *name)
   return NULL;
 }
 
-/**
- * shape_info_realise :
- * @info : the shape to realise
+/*!
+ * \brief After laoding and before drawing ShapeInfo needs to be realised
+ * @param : the shape to realise
  * 
  * Puts the ShapeInfo into a form suitable for actual use (lazy loading)
  *
+ * \extends _ShapeInfo
  */
-void shape_info_realise(ShapeInfo* info)
+void
+shape_info_realise(ShapeInfo* info)
 {
   GList* tmp;
   
@@ -210,6 +212,14 @@ is_subshape(xmlNode* node)
   return res;
 }
 
+/*!
+ * \brief Parse the SVG node from a shape file
+ * 
+ * Fill the ShapeInfo display list with GraphicElement each got from
+ * a single node within the shape's SVG part.
+ *
+ * \extends _ShapeInfo
+ */
 static void
 parse_svg_node(ShapeInfo *info, xmlNodePtr node, xmlNsPtr svg_ns,
                DiaSvgStyle *style, const gchar *filename)
@@ -661,6 +671,14 @@ update_bounds(ShapeInfo *info)
   }
 }
 
+/*!
+ * \brief Contructor for ShapeInfo from file
+ * 
+ * Load the full shape info from file potentially reusing the preloaded
+ * ShapeInfo loaded by shape_typeinfo_load()
+ *
+ * \extends _ShapeInfo
+ */
 static ShapeInfo *
 load_shape_info(const gchar *filename, ShapeInfo *preload)
 {
diff --git a/objects/custom/shape_info.h b/objects/custom/shape_info.h
index 870fbae..fba702a 100644
--- a/objects/custom/shape_info.h
+++ b/objects/custom/shape_info.h
@@ -164,20 +164,27 @@ typedef enum {
 #define DEFAULT_BORDER 0.25
 
 typedef struct _ShapeInfo ShapeInfo;
+/*!
+ * \brief Type information for a DiaObject created from shape file
+ *
+ * \ingroup ObjectCustom
+ */
 struct _ShapeInfo {
+  /*! The objects type name */
   gchar *name;
+  /*! The icon file to use */
   gchar *icon;
 
-  /* info required to load the real data on demand */
+  /*! the filename is info required to load the real data on demand */
   gchar *filename;
   gboolean loaded;
   
-  /* everything below could be put into it's own struct to also spare memory when the shapes are not created */
-  
+  /*! everything below could be put into it's own struct to also spare memory when the shapes are not created */
+  /* @{ */
   int nconnections;
   Point *connections;
-  int main_cp; /* The cp that gets connections from the whole object */
-  int object_flags;
+  int main_cp; /*!< the cp that gets connections from the whole object */
+  int object_flags; /*!< set of PropFlags e.g. parenting */
   Rectangle shape_bounds;
   gboolean has_text;
   gboolean resize_with_text;
@@ -187,7 +194,7 @@ struct _ShapeInfo {
   ShapeAspectType aspect_type;
   real aspect_min, aspect_max;
 
-  real default_width; /* unit cm as everything else internally in Dia */
+  real default_width; /*!< unit cm as everything else internally in Dia */
   real default_height;
 
 
@@ -203,6 +210,7 @@ struct _ShapeInfo {
 
   PropDescription *props;
   PropOffset *prop_offsets;
+  /* @} */
 };
 
 /* there is no destructor for ShapeInfo at the moment */
diff --git a/objects/custom/shape_typeinfo.c b/objects/custom/shape_typeinfo.c
index 3fb3d73..c4917d9 100644
--- a/objects/custom/shape_typeinfo.c
+++ b/objects/custom/shape_typeinfo.c
@@ -31,7 +31,10 @@
 #include <glib/gstdio.h>
 #include <libxml/parser.h>
 
-/*
+/*!
+ * \defgroup ObjectCustom Custom Shapes
+ * \ingroup Shapes
+ *
  * 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
@@ -40,7 +43,7 @@
  * 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 ...
+ * The startup time is significantly reduced by the lazy loading via XML SAX, too.
  */
 
 typedef enum {
@@ -171,6 +174,13 @@ _warning (void *ctx,
   va_end(args);
 }
 
+/*!
+ * \brief Partial load of ShapeInfo jsut for speed
+ * This functions loads the first BLOCKSSIZE block of a shape file
+ * to extract just the type information from it.
+ * \extends ShapeInfo
+ * \ingroup ObjectCustom
+ */
 gboolean
 shape_typeinfo_load (ShapeInfo* info)
 {