[dia] [dox] Some documentation for objects/standard

From: Hans Breuer <hans src gnome org>
To: commits-list gnome org
Cc:
Subject: [dia] [dox] Some documentation for objects/standard
Date: Sun, 9 Sep 2012 11:09:29 +0000 (UTC)
commit bd4f0d548da5d1e06d33e1a1177f7f28e2c6e92a
Author: Hans Breuer <hans breuer org>
Date:   Sun Sep 9 12:35:43 2012 +0200

    [dox] Some documentation for objects/standard

 objects/standard/arc.c        |   27 +++++++++-----
 objects/standard/bezier.c     |    5 +++
 objects/standard/beziergon.c  |    9 ++++-
 objects/standard/box.c        |    5 +++
 objects/standard/ellipse.c    |    5 +++
 objects/standard/image.c      |    5 +++
 objects/standard/line.c       |    5 +++
 objects/standard/outline.c    |   77 +++++++++++++++++++++++++++++++++++++---
 objects/standard/polygon.c    |    4 ++
 objects/standard/polyline.c   |    4 ++
 objects/standard/standard.c   |   10 +++++
 objects/standard/textobj.c    |    5 +++
 objects/standard/zigzagline.c |    5 +++
 13 files changed, 148 insertions(+), 18 deletions(-)
---
diff --git a/objects/standard/arc.c b/objects/standard/arc.c
index b220f86..2ba545e 100644
--- a/objects/standard/arc.c
+++ b/objects/standard/arc.c
@@ -16,6 +16,8 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  */
 
+ /*! \file arc.c -- Implementation of "Standard - Arc" */
+
 #include <config.h>
 
 #define _BSD_SOURCE 1 /* to get finite */
@@ -43,19 +45,24 @@
 
 typedef struct _Arc Arc;
 
+/*!
+ * \brief Standard - Arc : a portion of the circumference of a circle
+ * \extends _Connection
+ * \ingroup StandardObjects
+ */
 struct _Arc {
-  Connection connection;
-
-  Handle middle_handle;
-  Handle center_handle;
-
-  Color arc_color;
-  real curve_distance;
-  real line_width;
-  LineStyle line_style;
-  LineCaps line_caps;
-  real dashlength;
-  Arrow start_arrow, end_arrow;
+  Connection connection; /*!< inheritance */
+
+  Handle middle_handle; /*!< _Handle on the middle of the cicumference portion */
+  Handle center_handle; /*!< Handle on he center of the full circle */
+
+  Color arc_color; /*!< Color of the Arc */
+  real curve_distance; /*!< distance between middle_handle and chord */
+  real line_width; /*!< line width for the Arc */
+  LineStyle line_style; /*!< line style for the Arc */
+  LineCaps line_caps; /*!< line ends of the Arc */
+  real dashlength; /*!< part of the linestyle if not LINESTYLE_SOLID */
+  Arrow start_arrow, end_arrow; /*!< arrows */
 
   /* Calculated parameters: */
   real radius;
diff --git a/objects/standard/bezier.c b/objects/standard/bezier.c
index bbcd3ee..19e4d87 100644
--- a/objects/standard/bezier.c
+++ b/objects/standard/bezier.c
@@ -42,6 +42,11 @@
 
 typedef struct _Bezierline Bezierline;
 
+/*!
+ * \brief Standard - BezierLine : a bezier curve object
+ * \ingroup StandardObjects
+ * \extends _BezierConn
+ */
 struct _Bezierline {
   BezierConn bez;
 
diff --git a/objects/standard/beziergon.c b/objects/standard/beziergon.c
index 48c7e79..4a0f019 100644
--- a/objects/standard/beziergon.c
+++ b/objects/standard/beziergon.c
@@ -40,8 +40,11 @@
 
 #define DEFAULT_WIDTH 0.15
 
-typedef struct _BeziergonProperties BeziergonProperties;
-
+/*!
+ * \brief Standard - Beziergon: closed shape with bezier
+ * \extends _BezierShape
+ * \ingroup StandardObjects
+ */
 typedef struct _Beziergon {
   BezierShape bezier;
 
@@ -54,6 +57,8 @@ typedef struct _Beziergon {
   real line_width;
 } Beziergon;
 
+typedef struct _BeziergonProperties BeziergonProperties;
+
 static struct _BeziergonProperties {
   gboolean show_background;
 } default_properties = { TRUE };
diff --git a/objects/standard/box.c b/objects/standard/box.c
index 26260f8..d16b0df 100644
--- a/objects/standard/box.c
+++ b/objects/standard/box.c
@@ -47,6 +47,11 @@ typedef enum {
 
 typedef struct _Box Box;
 
+/*!
+ * \brief Standard - Box : rectangular box
+ * \extends _Element
+ * \ingroup StandardObjects
+ */
 struct _Box {
   Element element;
 
diff --git a/objects/standard/ellipse.c b/objects/standard/ellipse.c
index 7c768d6..cc938f6 100644
--- a/objects/standard/ellipse.c
+++ b/objects/standard/ellipse.c
@@ -45,6 +45,11 @@ typedef enum {
 
 typedef struct _Ellipse Ellipse;
 
+/*!
+ * \brief Standard - Ellipse
+ * \extends _Element
+ * \ingroup StandardObjects
+ */
 struct _Ellipse {
   Element element;
 
diff --git a/objects/standard/image.c b/objects/standard/image.c
index efb4a21..9c94b00 100644
--- a/objects/standard/image.c
+++ b/objects/standard/image.c
@@ -47,6 +47,11 @@
 
 typedef struct _Image Image;
 
+/*!
+ * \brief Standard - Image : rectangular image
+ * \extends _Element
+ * \ingroup StandardObjects
+ */
 struct _Image {
   Element element;
 
diff --git a/objects/standard/line.c b/objects/standard/line.c
index d3ab543..b212c0d 100644
--- a/objects/standard/line.c
+++ b/objects/standard/line.c
@@ -40,6 +40,11 @@
 
 typedef struct _LineProperties LineProperties;
 
+/*!
+ * \brief Standard - Line
+ * \extends _Connection
+ * \ingroup StandardObjects
+ */
 typedef struct _Line {
   Connection connection;
 
diff --git a/objects/standard/outline.c b/objects/standard/outline.c
index ee354bc..1e1c05a 100644
--- a/objects/standard/outline.c
+++ b/objects/standard/outline.c
@@ -20,6 +20,8 @@
  */
 
 /*!
+ * \file outline.c - finally rotated text, somwhat
+ *
  * A prototype for text effects with the standard renderer interface.
  * It should be possible to do all those fancy text effects like outline, rotate, ...
  * by converting text to pathes before rendering.
@@ -42,9 +44,14 @@
 #endif
 
 #define NUM_HANDLES 2
-/* Object definition */
+
+/*!
+ * \brief Standard - Outline
+ * \extends _DiaObject
+ * \ingroup StandardObjects
+ */
 typedef struct _Outline {
-  DiaObject object;
+  DiaObject object; /*!< inheritance */
   
   char *name;
   real rotation;
@@ -247,7 +254,13 @@ outine_update_handles(Outline *outline)
   obj->handles[1]->id = HANDLE_RESIZE_SE;
   obj->handles[1]->pos = outline->ink_rect[2];
 }
-/*! Not in the object interface but very important anyway. Used to recalculate the object data after a change  */
+/*!
+ * \brief Object update function called after property change
+ * 
+ * Not in the object interface but very important anyway.
+ * Used to recalculate the object data after a change
+ * \protected \memberof Outline
+ */
 static void
 outline_update_data (Outline *outline)
 {
@@ -323,6 +336,11 @@ outline_update_data (Outline *outline)
   /* the cairo context is only used in this fuinction */
   cairo_destroy (cr);
 }
+/*!
+ * \brief Object drawing to the given renderer
+ *
+ * \memberof Outline
+ */
 static void 
 outline_draw(Outline *outline, DiaRenderer *renderer)
 {
@@ -433,14 +451,26 @@ outline_draw(Outline *outline, DiaRenderer *renderer)
   if (i - n - 1 > 0)
     DIA_RENDERER_GET_CLASS (renderer)->draw_bezier (renderer, &pts[n], i - n - 1, &outline->line_color);
 }
-/* returning used to crash Dia, the method needed to be NULL if there is nothing to do */
+/*!
+ * \brief Optionally deliver an object specific menu
+ *
+ * returning NULL used to crash Dia, the method itself needed to be NULL if there is nothing to do
+ *
+ * \memberof Outline
+ */
 static DiaMenu *
 outline_get_object_menu(Outline *outline, Point *clickedpoint)
 {
   return NULL;
 }
 
-/*! A standard props compliant object needs to describe its parameters */
+/*!
+ * \brief Descibe the object parameters (bot it's values)
+ *
+ * A standard props compliant object needs to describe its parameters
+ *
+ * \memberof Outline
+ */
 static PropDescription *
 outline_describe_props (Outline *outline)
 {
@@ -448,22 +478,38 @@ outline_describe_props (Outline *outline)
     prop_desc_list_calculate_quarks(outline_props);
   return outline_props;
 }
+/*!
+ * \brief Fill a properties vector reflecting the current state of the object
+ * \memberof Outline
+ */
 static void 
 outline_get_props (Outline *outline, GPtrArray *props)
 {
   object_get_props_from_offsets(&outline->object, outline_offsets, props);
 }
+/*!
+ * \brief Set the object state from the given proeprty vector
+ * \memberof Outline
+ */
 static void 
 outline_set_props (Outline *outline, GPtrArray *props)
 {
   object_set_props_from_offsets(&outline->object, outline_offsets, props);
   outline_update_data (outline);
 }
+/*!
+ * \brief Calculate the distance of the whole object to the given point
+ * \memberof Outline
+ */
 static real
 outline_distance_from (Outline *outline, Point *point)
 {
   return distance_polygon_point (&outline->ink_rect[0], 4, outline->line_width, point);
 }
+/*!
+ * \brief Move one of the objects handles
+ * \memberof Outline
+ */
 static ObjectChange* 
 outline_move_handle (Outline *outline,
                      Handle *handle,
@@ -499,6 +545,14 @@ outline_move_handle (Outline *outline,
   }
   return NULL;
 }
+/*!
+ * \brief Move the whole object to the given position
+ * 
+ * If the object position does not change the whole object should not either.
+ * This is used as a kludge to call the protected update_data() function
+ *
+ * \memberof Outline
+ */
 static ObjectChange* 
 outline_move (Outline *outline, Point *to)
 {
@@ -509,6 +563,10 @@ outline_move (Outline *outline, Point *to)
   outline_update_data (outline);
   return NULL;
 }
+/*!
+ * \brief Create a deep copy of the object
+ * \memberof Outline
+ */
 static DiaObject *
 outline_copy (Outline *from)
 {
@@ -530,6 +588,10 @@ outline_copy (Outline *from)
 
   return &to->object;
 }
+/*!
+ * \brief Destruction of the object
+ * \memberof Outline
+ */
 static void 
 outline_destroy (Outline *outline)
 {
@@ -539,6 +601,10 @@ outline_destroy (Outline *outline)
   object_destroy(&outline->object);
   /* but not the object itself? */
 }
+/*!
+ * \brief Change the object state regarding selection 
+ * \memberof Outline
+ */
 static void 
 outline_select (Outline *outline, Point *clicked_point,
 		DiaRenderer *interactive_renderer)
@@ -547,4 +613,3 @@ outline_select (Outline *outline, Point *clicked_point,
 }
 
 #endif /* HAVE_CAIRO */
-
diff --git a/objects/standard/polygon.c b/objects/standard/polygon.c
index 80ef88b..69cd55a 100644
--- a/objects/standard/polygon.c
+++ b/objects/standard/polygon.c
@@ -46,6 +46,10 @@ Fix crashes:)
 
 #define DEFAULT_WIDTH 0.15
 
+/*!
+ * \brief Standard - Polygon
+ * \extends _PolyShape
+ */
 typedef struct _Polygon {
   PolyShape poly;
 
diff --git a/objects/standard/polyline.c b/objects/standard/polyline.c
index dc477e2..74c4967 100644
--- a/objects/standard/polyline.c
+++ b/objects/standard/polyline.c
@@ -38,6 +38,10 @@
 
 #define DEFAULT_WIDTH 0.15
 
+/*!
+ * \brief Standard - PolyLine
+ * \extends _PolyConn
+ */
 typedef struct _Polyline {
   PolyConn poly;
 
diff --git a/objects/standard/standard.c b/objects/standard/standard.c
index 412c512..bde0968 100644
--- a/objects/standard/standard.c
+++ b/objects/standard/standard.c
@@ -25,6 +25,16 @@
 #include "intl.h"
 #include "plug-ins.h"
 
+/*!
+\defgroup StandardObjects Standard Objects
+\ingroup Objects
+
+The minimal set of objects available to Dia is defined in the directory objects/standard.
+Although implmented as a plug-in Dia wont start without it being loaded.
+These objects are not only referenced directly in the toolbox and application menu,
+but they also are required for most of Dia's diagram importers.
+*/
+
 extern DiaObjectType *_arc_type;
 extern DiaObjectType *_box_type;
 extern DiaObjectType *_ellipse_type;
diff --git a/objects/standard/textobj.c b/objects/standard/textobj.c
index be191f1..5e7483d 100644
--- a/objects/standard/textobj.c
+++ b/objects/standard/textobj.c
@@ -45,6 +45,11 @@ enum _Valign {
         VALIGN_FIRST_LINE
 };
 typedef struct _Textobj Textobj;
+/*!
+ * \brief Standard - Text
+ * \extends _DiaObject
+ * \ingroup StandardObjects
+ */
 struct _Textobj {
   DiaObject object;
   
diff --git a/objects/standard/zigzagline.c b/objects/standard/zigzagline.c
index 4aaa946..e0119e4 100644
--- a/objects/standard/zigzagline.c
+++ b/objects/standard/zigzagline.c
@@ -38,6 +38,11 @@
 
 #define HANDLE_MIDDLE HANDLE_CUSTOM1
 
+/*!
+ * \brief Standard - ZigZagLine : orthogonal connection object
+ * \extends _OrthConn
+ * \ingroup StandardObjects
+ */
 typedef struct _Zigzagline {
   OrthConn orth;
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]