[dia] style: various gtk-doc fixes

[Zander <zbrown src gnome org>]

commit 6131d0623c9d8e84efd129b1624db4e985e9404f
Author: Zander Brown <zbrown gnome org>
Date:   Wed Sep 11 16:27:43 2019 +0100

    style: various gtk-doc fixes

 lib/bezier-common.c   |  23 +++++++-----
 lib/color.c           |  87 ++++++++++++++++++++++++++-----------------
 lib/connectionpoint.c |  61 +++++++++++++++++++-----------
 lib/connectionpoint.h | 101 ++++++++++++++++++++++++++------------------------
 lib/create.c          |   7 +++-
 lib/debug.c           |  20 ++++++----
 lib/dia_image.c       |  14 +++++--
 lib/dia_image.h       |  18 +++++++--
 lib/dia_svg.c         |  71 +++++++++++++++++++----------------
 lib/diaerror.c        |  11 ++++--
 lib/dialib.c          |  23 +++++++-----
 lib/dialogs.c         |  85 +++++++++++++++++++++++++++---------------
 lib/filter.c          |   6 ++-
 lib/object_defaults.c |   7 ++--
 lib/persistence.c     |   7 +++-
 lib/prop_text.c       |   4 +-
 16 files changed, 337 insertions(+), 208 deletions(-)
---
diff --git a/lib/bezier-common.c b/lib/bezier-common.c
index fef28adc..524a8e99 100644
--- a/lib/bezier-common.c
+++ b/lib/bezier-common.c
@@ -22,7 +22,7 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  */
 
-#include "config.h" 
+#include "config.h"
 
 #include "bezier-common.h"
 #include "diarenderer.h"
@@ -47,7 +47,7 @@ bezier_calc_corner_types (BezierCommon *bezier)
   bezier->corner_types = g_realloc (bezier->corner_types, bezier->num_points * sizeof(BezCornerType));
   bezier->corner_types[0] = BEZ_CORNER_CUSP;
   bezier->corner_types[num-1] = BEZ_CORNER_CUSP;
-  
+
   for (i = 0; i < num - 2; ++i) {
     const Point *start = &bezier->points[i].p2;
     const Point *major = &bezier->points[i].p3;
@@ -59,7 +59,7 @@ bezier_calc_corner_types (BezierCommon *bezier)
       bezier->corner_types[i+1] = BEZ_CORNER_CUSP;
     else if (distance_line_point (start, end, 0, major) > tolerance)
       bezier->corner_types[i+1] = BEZ_CORNER_CUSP;
-    else if (fabs (   distance_point_point (start, major) 
+    else if (fabs (   distance_point_point (start, major)
                   -  distance_point_point (end, major) > tolerance))
       bezier->corner_types[i+1] = BEZ_CORNER_SMOOTH;
     else
@@ -67,14 +67,19 @@ bezier_calc_corner_types (BezierCommon *bezier)
   }
 }
 
-/** Set a bezier to use the given array of points.
+/**
+ * beziercommon_set_points:
+ * @bezier: A #BezierCommon to operate on
+ * @num_points: The number of points in the `points' array.
+ * @points: The new points that this bezier should be set to use.
+ *
+ * Set a bezier to use the given array of points.
  * This function does *not* set up handles
- * @param bezier A bezier to operate on
- * @param num_points The number of points in the `points' array.
- * @param points The new points that this bezier should be set to use.
  */
 void
-beziercommon_set_points (BezierCommon *bezier, int num_points, const BezPoint *points)
+beziercommon_set_points (BezierCommon   *bezier,
+                         int             num_points,
+                         const BezPoint *points)
 {
   int i;
 
@@ -166,7 +171,7 @@ bezier_draw_control_lines (int          num_points,
   Color line_colour = { 0.0, 0.0, 0.6, 1.0 };
   Point startpoint;
   int i;
-  
+
   /* setup renderer ... */
   DIA_RENDERER_GET_CLASS(renderer)->set_linewidth(renderer, 0);
   DIA_RENDERER_GET_CLASS(renderer)->set_linestyle(renderer, LINESTYLE_DOTTED, 1);
diff --git a/lib/color.c b/lib/color.c
index 72231d6b..4c1be67c 100644
--- a/lib/color.c
+++ b/lib/color.c
@@ -15,7 +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.
  */
- 
+
 #include <config.h>
 
 #include <stdio.h>
@@ -26,22 +26,25 @@
 
 static GdkColormap *colormap = NULL;
 
-#ifndef G_OS_WIN32 
+#ifndef G_OS_WIN32
 Color color_black = { 0.0f, 0.0f, 0.0f, 1.0f };
 Color color_white = { 1.0f, 1.0f, 1.0f, 1.0f };
 #endif
 
 gboolean _color_initialized = FALSE;
 
-/** Initialize color access (gdk) and set up default colors.
+/**
+ * color_init:
+ *
+ * Initialize color access (gdk) and set up default colors.
  */
-void 
-color_init(void)
+void
+color_init (void)
 {
   if (!_color_initialized) {
 #if !defined(GDK_WINDOWING_QUARTZ)
     GdkVisual *visual = gtk_widget_get_default_visual();
-    colormap = gdk_colormap_new (visual, FALSE); 
+    colormap = gdk_colormap_new (visual, FALSE);
 #else
     /* gdk/quartz does not implement gdk_colormap_new () */
     colormap = gdk_screen_get_system_colormap (gdk_screen_get_default ());
@@ -51,17 +54,21 @@ color_init(void)
   }
 }
 
-/** Allocate a new color object wtih the given values.
+/**
+ * color_new_rgb:
+ * @r: Red component (0 <= r <= 1)
+ * @g: Green component (0 <= g <= 1)
+ * @b: Blue component (0 <= b <= 1)
+ *
+ * Allocate a new color object wtih the given values.
  * Initializes alpha component to 1.0
- * @param r Red component (0 <= r <= 1)
- * @param g Green component (0 <= g <= 1)
- * @param b Blue component (0 <= b <= 1)
- * @returns A newly allocated color object.  This should be freed after use.
+ *
+ * Returns: A newly allocated color object.  This should be freed after use.
  */
 Color *
-color_new_rgb(float r, float g, float b)
+color_new_rgb (float r, float g, float b)
 {
-  Color *col = g_new(Color, 1);
+  Color *col = g_new (Color, 1);
   col->red = r;
   col->green = g;
   col->blue = b;
@@ -69,17 +76,21 @@ color_new_rgb(float r, float g, float b)
   return col;
 }
 
-/** Allocate a new color object wtih the given values.
- * @param r Red component (0 <= r <= 1)
- * @param g Green component (0 <= g <= 1)
- * @param b Blue component (0 <= b <= 1)
- * @param alpha Alpha component (0 <= alpha <= 1)
- * @returns A newly allocated color object.  This should be freed after use.
+/**
+ * color_new_rgba:
+ * @r: Red component (0 <= r <= 1)
+ * @g: Green component (0 <= g <= 1)
+ * @b: Blue component (0 <= b <= 1)
+ * @alpha: Alpha component (0 <= alpha <= 1)
+ *
+ * Allocate a new color object wtih the given values.
+ *
+ * Returns: A newly allocated color object.  This should be freed after use.
  */
 Color *
-color_new_rgba(float r, float g, float b, float alpha)
+color_new_rgba (float r, float g, float b, float alpha)
 {
-  Color *col = g_new(Color, 1);
+  Color *col = g_new (Color, 1);
   col->red = r;
   col->green = g;
   col->blue = b;
@@ -87,35 +98,43 @@ color_new_rgba(float r, float g, float b, float alpha)
   return col;
 }
 
-/** Convert a Dia color object to GDK style, including handling allocation.
- * @param color A color object.  This will not be kept by this function.
- * @param gdkcolor Return value: GDK color object to fill in.
+/**
+ * color_convert:
+ * @color: A #Color object. This will not be kept by this function.
+ * @gdkcolor: (out): GDK color object to fill in.
+ *
+ * Convert a Dia color object to GDK style, including handling allocation.
  */
 void
-color_convert(const Color *color, GdkColor *gdkcolor)
+color_convert (const Color *color, GdkColor *gdkcolor)
 {
   gdkcolor->red = (guint16)(color->red*65535);
   gdkcolor->green = (guint16)(color->green*65535);
   gdkcolor->blue = (guint16)(color->blue*65535);
 
   if (_color_initialized) {
-    if (!gdk_colormap_alloc_color (colormap, gdkcolor, TRUE, TRUE))
+    if (!gdk_colormap_alloc_color (colormap, gdkcolor, TRUE, TRUE)) {
       g_warning ("color_convert failed.");
+    }
   } else {
     g_warning("Can't color_convert in non-interactive app (w/o color_init())");
   }
 }
 
-/** Compare two color objects.
- * @param color1 One color object
- * @param color2 Another color object.
- * @returns TRUE if the color objects are the same color.
+/**
+ * color_equals:
+ * @color1: One #Color object
+ * @color2: Another #Color object.
+ *
+ * Compare two colour objects.
+ *
+ * Returns: %TRUE if the colour objects are the same colour.
  */
 gboolean
-color_equals(const Color *color1, const Color *color2)
+color_equals (const Color *color1, const Color *color2)
 {
   return (color1->red == color2->red) &&
-    (color1->green == color2->green) &&
-    (color1->blue == color2->blue) &&
-    (color1->alpha == color2->alpha);
+         (color1->green == color2->green) &&
+         (color1->blue == color2->blue) &&
+         (color1->alpha == color2->alpha);
 }
diff --git a/lib/connectionpoint.c b/lib/connectionpoint.c
index 5ea5b1bd..d4347330 100644
--- a/lib/connectionpoint.c
+++ b/lib/connectionpoint.c
@@ -19,27 +19,39 @@
 #include "config.h"
 #include "connectionpoint.h"
 
-/** Returns the available directions on a slope.
+/**
+ * SECTION:dia-connectionpoint
+ * @title: ConnectionPoint
+ * @short_description: Connections between #DiaObjects
+ *
+ * #ConnectionPoints together with #Handles allow to connect objects
+ */
+
+/**
+ * find_slope_directions:
+ * @from: Beginning of the slope line.
+ * @to: End of the slope line.
+ *
+ * Returns the available directions on a slope.
  * The right-hand side of the line is assumed to be within the object,
  * and thus not available.
- * @param from Beginning of the slope line.
- * @param to End of the slope line.
- * @returns The directions open (@see connectionpoint.h) open on the left-hand
+ *
+ * Returns: The directions open (see #ConnectionPointDirection) open on the left-hand
  *  side of the slope.
  */
 gint
-find_slope_directions(Point from, Point to)
+find_slope_directions (Point from, Point to)
 {
   gint dirs;
   gint slope;
 
-  if (fabs(from.y-to.y) < 0.0000001)
+  if (fabs (from.y-to.y) < 0.0000001)
     return (from.x > to.x?DIR_SOUTH:DIR_NORTH);
-  if (fabs(from.x-to.x) < 0.0000001)
+  if (fabs (from.x-to.x) < 0.0000001)
     return (from.y > to.y?DIR_WEST:DIR_EAST);
 
-  point_sub(&to, &from);
-  slope = fabs(to.y/to.x);
+  point_sub (&to, &from);
+  slope = fabs (to.y/to.x);
 
   dirs = 0;
   if (slope < 2) { /* Flat enough to allow north-south */
@@ -60,28 +72,35 @@ find_slope_directions(Point from, Point to)
 }
 
 
-/** Update the object-settable parts of a connectionpoints.
- * @param p A ConnectionPoint pointer (non-NULL).
- * @param x The x coordinate of the connectionpoint.
- * @param y The y coordinate of the connectionpoint.
- * @param dirs The directions that are open for connections on this point.
+/**
+ * connpoint_update:
+ * @p: A ConnectionPoint pointer (non-%NULL).
+ * @x: The x coordinate of the connectionpoint.
+ * @y: The y coordinate of the connectionpoint.
+ * @dirs: The directions that are open for connections on this point.
+ *
+ * Update the object-settable parts of a connectionpoints.
  */
-void 
-connpoint_update(ConnectionPoint *p, real x, real y, gint dirs)
+void
+connpoint_update (ConnectionPoint *p, real x, real y, gint dirs)
 {
   p->pos.x = x;
   p->pos.y = y;
   p->directions = dirs;
 }
 
-/** Returns TRUE if the given connection point is non-null and autogapped.
- * @param cp A connectionpoint.
- * @returns TRUE if the given connection point is non-null and has the
- *  CP_FLAG_AUTOGAP flag set (i.e. lines connecting to it should try to end
+/**
+ * connpoint_is_autogap:
+ * @cp: A #ConnectionPoint.
+ *
+ * Returns %TRUE if the given connection point is non-null and autogapped.
+ *
+ * Returns: %TRUE if the given connection point is non-null and has the
+ *  %CP_FLAG_AUTOGAP flag set (i.e. lines connecting to it should try to end
  *  at the border of the object instead of at the connection point.
  */
 gboolean
-connpoint_is_autogap(ConnectionPoint *cp)
+connpoint_is_autogap (ConnectionPoint *cp)
 {
   return cp != NULL && (cp->flags & CP_FLAG_AUTOGAP) && (cp->connected != NULL);
 }
diff --git a/lib/connectionpoint.h b/lib/connectionpoint.h
index 9cbff593..ca2a66fe 100644
--- a/lib/connectionpoint.h
+++ b/lib/connectionpoint.h
@@ -16,10 +16,6 @@
  * 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
- */
 #ifndef CONNECTIONPOINT_H
 #define CONNECTIONPOINT_H
 
@@ -27,10 +23,22 @@
 #include <glib.h>
 #include "geometry.h"
 
-/*! \brief Connections directions, used as hints to e.g. zigzaglines 
+/**
+ * ConnectionPointDirection:
+ * @DIR_NONE: None
+ * @DIR_NORTH: North
+ * @DIR_EAST: East
+ * @DIR_SOUTH: South
+ * @DIR_WEST: West
+ * @DIR_NORTHEAST: %DIR_NORTH + %DIR_EAST
+ * @DIR_SOUTHEAST: %DIR_SOUTH + %DIR_EAST
+ * @DIR_NORTHWEST: %DIR_NORTH + %DIR_WEST
+ * @DIR_SOUTHWEST: %DIR_SOUTH + %DIR_WEST
+ * @DIR_ALL: All directions
+ *
+ * Connections directions, used as hints to e.g. zigzaglines
  * Ordered this way to let *2 be rotate clockwise, /2 rotate counterclockwise.
  * Used as bits
- * \ingroup ObjectConnects
  */
 typedef enum {
   DIR_NONE  = 0,
@@ -46,56 +54,53 @@ typedef enum {
   DIR_ALL       = (DIR_NORTH|DIR_SOUTH|DIR_EAST|DIR_WEST)
 } ConnectionPointDirection;
 
-/*!
- * \brief Additional behaviour flags for connection points
- * \ingroup ObjectConnects
+/**
+ * ConnectionPointFlags:
+ * @CP_FLAG_ANYPLACE: Set if this connpoint is the one that
+                      is connected to when a connection is
+                      dropped on an object.
+ * @CP_FLAG_AUTOGAP: Set if this connpoint is internal
+                     and so should force a gap on the lines.
+ * @CP_FLAGS_MAIN: Use this for the central CP that
+                   takes connections from all over the
+                   object and has autogap.
+ *
+ * Additional behaviour flags for connection points
+ *
+ * Most non-connection objects want exactly one %CP_FLAGS_MAIN #ConnectionPoint
+ * in the middle.
  */
 typedef enum {
-  CP_FLAG_ANYPLACE = (1<<0), /*!< Set if this connpoint is the one that
-                                 is connected to when a connection is
-                                 dropped on an object. */
-  CP_FLAG_AUTOGAP =  (1<<1), /*!< Set if this connpoint is internal
-                                 and so should force a gap on the lines. */
-
-  /*! Most non-connection objects want exactly one CP with this, in the middle. */
-  CP_FLAGS_MAIN        =   (CP_FLAG_ANYPLACE|CP_FLAG_AUTOGAP) /*!< Use this for the central CP that
-                                                           takes connections from all over the
-                                                           object and has autogap. */
+  CP_FLAG_ANYPLACE = (1<<0),
+  CP_FLAG_AUTOGAP  = (1<<1),
+  CP_FLAGS_MAIN    = (CP_FLAG_ANYPLACE|CP_FLAG_AUTOGAP)
 } ConnectionPointFlags;
 
-/*!
- * \brief To connect object with other objects handles
- * \ingroup ObjectConnects
+/**
+ * ConnectionPoint:
+ * @pos: position of this connection point
+ * @object: pointer to the object having this point
+ * @connected: list of #DiaObject connected to this point
+ * @directions: Directions that this connection point is open to
+ * @flags: Flags set for this connpoint. See #ConnectionPointFlags
+ *
+ * To connect object with other objects handles
  */
 struct _ConnectionPoint {
-  Point pos;         /*!< position of this connection point */
-  DiaObject *object; /*!< pointer to the object having this point */
-  GList *connected;  /*!< list of 'DiaObject *' connected to this point*/
-  guint8 directions; /*!< Directions that this connection point is open to */
-  guint8 flags;      /*!< Flags set for this connpoint.  See CP_FLAGS_* above. */
+  Point      pos;
+  DiaObject *object;
+  GList     *connected;
+  guint8     directions;
+  guint8     flags;
 };
 
-/** 
- * \brief Returns the available directions on a slope.
- * The right-hand side of the line is assumed to be within the object,
- * and thus not available. 
- * \ingroup ObjectConnects
- */
-gint find_slope_directions(Point from, Point to);
-/*!
- * \brief Update the object-settable parts of a connectionpoints.
- * @param p A ConnectionPoint pointer (non-NULL).
- * @param x The x coordinate of the connectionpoint.
- * @param y The y coordinate of the connectionpoint.
- * @param dirs The directions that are open for connections on this point.
- * \ingroup ObjectConnects
- */
-void connpoint_update(ConnectionPoint *p, real x, real y, gint dirs);
-/*!
- * \brief Adaptive rendering to the boundary of the connected object
- * \ingroup ObjectConnects
- */
-gboolean connpoint_is_autogap(ConnectionPoint *cp);
+gint     find_slope_directions (Point            from,
+                                Point            to);
+void     connpoint_update      (ConnectionPoint *p,
+                                real             x,
+                                real             y,
+                                gint             dirs);
+gboolean connpoint_is_autogap  (ConnectionPoint *cp);
 
 
 #endif /* CONNECTIONPOINT_H */
diff --git a/lib/create.c b/lib/create.c
index 913baf2d..35b9a48a 100644
--- a/lib/create.c
+++ b/lib/create.c
@@ -16,7 +16,12 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  */
 
-/** This file contains functions for importers in particular to create
+/**
+ * SECTION:dia-create
+ * @title: Create
+ * @short_description: Construct objects
+ *
+ * This file contains functions for importers in particular to create
  * standard objects.
  */
 
diff --git a/lib/debug.c b/lib/debug.c
index 348069b3..6c1e739b 100644
--- a/lib/debug.c
+++ b/lib/debug.c
@@ -26,19 +26,23 @@
 
 #include "debug.h"
 
-/** Output a message if the given value is not true. 
- * @param val A value to test. 
- * @param format A printf-style message to output if the value is false.
- * @return val
+/**
+ * dia_assert_true:
+ * @val: A value to test.
+ * @format: A printf-style message to output if the value is false.
+ *
+ * Output a message if the given value is not true.
+ *
+ * Returns: @val
  */
 gboolean
-dia_assert_true(gboolean val, const gchar *format, ...)
+dia_assert_true (gboolean val, const gchar *format, ...)
 {
   va_list args;
   if (!val) {
-    va_start(args, format);
-    g_vprintf(format, args);
-    va_end(args);
+    va_start (args, format);
+    g_vprintf (format, args);
+    va_end (args);
   }
   return val;
 }
diff --git a/lib/dia_image.c b/lib/dia_image.c
index e353fb69..06949c0f 100644
--- a/lib/dia_image.c
+++ b/lib/dia_image.c
@@ -192,8 +192,11 @@ dia_image_new_from_pixbuf (GdkPixbuf *pixbuf)
   return dia_img;
 }
 
-/** Reference an image.
- * @param image Image that we want a reference to.
+/**
+ * dia_image_add_ref:
+ * @image: Image that we want a reference to.
+ *
+ * Reference an image.
  */
 void
 dia_image_add_ref (DiaImage *image)
@@ -202,8 +205,11 @@ dia_image_add_ref (DiaImage *image)
   g_object_ref (image);
 }
 
-/** Release a reference to an image.
- * @param image Image to unreference.
+/**
+ * dia_image_unref:
+ * @image: Image to unreference.
+ *
+ * Release a reference to an image.
  */
 void
 dia_image_unref (DiaImage *image)
diff --git a/lib/dia_image.h b/lib/dia_image.h
index 5defb3b9..64c9dd8b 100644
--- a/lib/dia_image.h
+++ b/lib/dia_image.h
@@ -43,17 +43,29 @@ gboolean         dia_image_save              (DiaImage       *image,
 int              dia_image_width             (const DiaImage *image);
 int              dia_image_rowstride         (const DiaImage *image);
 int              dia_image_height            (const DiaImage *image);
-/** Returns a copy of the RGB data in this image with any alpha stripped
+/**
+ * dia_image_rgb_data:
+ * @image: the #DiaImage
+ *
+ * Returns: a copy of the RGB data in this image with any alpha stripped
  * The returned buffer must be freed after use.
  * The buffer is laid out as dia_image_width*dia_image_rowstride*3 bytes.
  */
 guint8          *dia_image_rgb_data          (const DiaImage *image);
-/** Returns a copy of the alpha data in this image, or NULL if none
+/**
+ * dia_image_mask_data:
+ * @image: the #DiaImage
+ *
+ * Returns: a copy of the alpha data in this image, or %NULL if none
  * The returned buffer must be freed after use.
  * The buffer is laid out as dia_image_width*dia_image_height bytes.
  */
 guint8          *dia_image_mask_data         (const DiaImage *image);
-/** Returns the RGBA data in this image, or NULL if there's no alpha.
+/**
+ * dia_image_rgba_data:
+ * @image: the #DiaImage
+ *
+ * Returns: the RGBA data in this image, or NULL if there's no alpha.
  * Note that this is the raw data, not a copy.
  */
 const guint8    *dia_image_rgba_data         (const DiaImage *image);
diff --git a/lib/dia_svg.c b/lib/dia_svg.c
index 4f0b3b3c..82347f71 100644
--- a/lib/dia_svg.c
+++ b/lib/dia_svg.c
@@ -65,7 +65,7 @@ dia_svg_style_init(DiaSvgStyle *gs, DiaSvgStyle *parent_style)
   gs->dashlength = parent_style ? parent_style->dashlength : 1;
   /* http://www.w3.org/TR/SVG/painting.html#FillProperty - default black
    * but we still have to see the difference
-   */ 
+   */
   gs->fill = parent_style ? parent_style->fill : DIA_SVG_COLOUR_DEFAULT;
   gs->fill_opacity = parent_style ? parent_style->fill_opacity : 1.0;
   gs->linecap = parent_style ? parent_style->linecap : LINECAPS_DEFAULT;
@@ -299,7 +299,7 @@ svg_named_color (const char *name, gint32 *color)
 
   return FALSE;
 }
-/*! 
+/*!
  * \brief Parse an SVG color description.
  *
  * @param color A place to store the color information (0RGB)
@@ -513,8 +513,8 @@ _style_adjust_font (DiaSvgStyle *s, const char *family, const char *style, const
      */
     s->font = dia_font_new_from_style(DIA_FONT_SANS, s->font_height > 0 ? s->font_height : 1.0);
     if (family) {
-      /* SVG allows a list of families here, also there is some strange formatting 
-       * seen, like 'Arial'. If the given family name can not be resolved by 
+      /* SVG allows a list of families here, also there is some strange formatting
+       * seen, like 'Arial'. If the given family name can not be resolved by
        * Pango it complaints loudly with g_warning().
        */
       gchar **families = g_strsplit(family, ",", -1);
@@ -833,7 +833,7 @@ dia_svg_parse_style(xmlNodePtr node, DiaSvgStyle *s, real user_scale)
       _parse_linecap (s, (gchar *)str);
     xmlFree(str);
   }
-  
+
   /* text-props, again ;( */
   str = xmlGetProp(node, (const xmlChar *)"font-size");
   if (str) {
@@ -931,25 +931,34 @@ _path_arc_segment(GArray* points,
   g_array_append_val(points, bez);
 }
 
-/** Parse an SVG description of a full arc.
- * @param points
- * @param cpx
- * @param cpy
- * @param rx
- * @param ry
- * @param x_axis_rotation
- * @param large_arc_flag
- * @param sweep_flag
- * @param x
- * @param y
- * @param last_p2
+/**
+ * _path_arc:
+ * @points:
+ * @cpx:
+ * @cpy:
+ * @rx:
+ * @ry:
+ * @x_axis_rotation:
+ * @large_arc_flag:
+ * @sweep_flag:
+ * @x:
+ * @y:
+ * @last_p2:
+ *
+ * Parse an SVG description of a full arc.
  */
 static void
-_path_arc(GArray *points, double cpx, double cpy,
-          double rx, double ry, double x_axis_rotation,
-          int large_arc_flag, int sweep_flag,
-          double x, double y,
-          Point *last_p2)
+_path_arc (GArray *points,
+           double  cpx,
+           double  cpy,
+           double  rx,
+           double  ry,
+           double  x_axis_rotation,
+           int     large_arc_flag,
+           int     sweep_flag,
+           double  x,
+           double  y,
+           Point  *last_p2)
 {
     double sin_th, cos_th;
     double a00, a01, a10, a11;
@@ -1049,7 +1058,7 @@ _path_arc(GArray *points, double cpx, double cpy,
  * zigzaglines into their appropriate objects?  Could either be done by
  * returning an object or by having functions that try parsing as
  * specific simple paths.
- * NOPE: Dia is capable to handle beziers and the file has given us some so 
+ * NOPE: Dia is capable to handle beziers and the file has given us some so
  * WHY should be break it in to pieces ???
  */
 gboolean
@@ -1259,8 +1268,8 @@ dia_svg_parse_path(GArray *points, const gchar *path_str, gchar **unparsed,
        g_array_index(points,BezPoint,0) = bez;
       else
         g_array_append_val(points, bez);
-      /* [SVG11 8.3.2] If a moveto is followed by multiple pairs of coordinates, 
-       * the subsequent pairs are treated as implicit lineto commands 
+      /* [SVG11 8.3.2] If a moveto is followed by multiple pairs of coordinates,
+       * the subsequent pairs are treated as implicit lineto commands
        */
       last_type = PATH_LINE;
       break;
@@ -1274,8 +1283,8 @@ dia_svg_parse_path(GArray *points, const gchar *path_str, gchar **unparsed,
        bez.p1.x += last_point.x;
        bez.p1.y += last_point.y;
       }
-      /* Strictly speeaking it should not be necessary to assign the other 
-       * two points. But it helps hiding a serious limitation with the 
+      /* Strictly speeaking it should not be necessary to assign the other
+       * two points. But it helps hiding a serious limitation with the
        * standard bezier serialization, namely only saving one move-to
        * and the rest as curve-to */
 #define INIT_LINE_TO_AS_CURVE_TO bez.p3 = bez.p1; bez.p2 = last_point
@@ -1475,7 +1484,7 @@ dia_svg_parse_path(GArray *points, const gchar *path_str, gchar **unparsed,
        }
 
        /* avoid matherr with bogus values - just ignore them
-        * does happen e.g. with 'Chem-Widgets - clamp-large' 
+        * does happen e.g. with 'Chem-Widgets - clamp-large'
         */
        if (last_point.x != dest.x || last_point.y != dest.y)
          _path_arc (points, last_point.x, last_point.y,
@@ -1539,7 +1548,7 @@ _parse_transform (const gchar *trans, DiaMatrix *m, real scale)
   gchar *p = strchr (trans, '(');
   int i = 0;
 
-  while (   (*trans != '\0') 
+  while (   (*trans != '\0')
          && (*trans == ' ' || *trans == ',' || *trans == '\t' || *trans == '\n' || *trans == '\r'))
     ++trans; /* skip whitespace */
 
@@ -1576,7 +1585,7 @@ _parse_transform (const gchar *trans, DiaMatrix *m, real scale)
   } else if (strncmp (trans, "rotate", 6) == 0) {
     DiaMatrix translate = {1, 0, 0, 1, 0, 0 };
     real angle;
-    
+
     if (list[i])
       angle = g_ascii_strtod (list[i], NULL), ++i;
     else {
@@ -1670,7 +1679,7 @@ dia_svg_from_matrix(const DiaMatrix *matrix, real scale)
   g_string_append (sm, buf); g_string_append (sm, ",");
   g_ascii_formatd (buf, sizeof(buf), "%g", matrix->y0 * scale);
   g_string_append (sm, buf); g_string_append (sm, ")");
-  
+
   s = sm->str;
   g_string_free (sm, FALSE);
   return s;
diff --git a/lib/diaerror.c b/lib/diaerror.c
index 5c713532..99e684a5 100644
--- a/lib/diaerror.c
+++ b/lib/diaerror.c
@@ -19,12 +19,17 @@
 #include "diaerror.h"
 
 
-/** Get the error quark
+/**
+ * dia_error_quark:
+ *
+ * Get the error quark
+ *
  * This quark is apparently only used in proplist_load.
- * @return An quark for GError creation.
+ *
+ * Returns: An quark for %GError creation.
  */
 GQuark
-dia_error_quark(void)
+dia_error_quark (void)
 {
   static GQuark q = 0;
   if (!q)
diff --git a/lib/dialib.c b/lib/dialib.c
index 2d99e66c..3e413bbc 100644
--- a/lib/dialib.c
+++ b/lib/dialib.c
@@ -52,16 +52,16 @@ stderr_message_internal(const char *title, enum ShowAgainStyle showAgain,
   if (len >= alloc) {
     if (buf)
       g_free (buf);
-    
+
     alloc = nearest_pow (MAX(len + 1, 1024));
-    
+
     buf = g_new (char, alloc);
   }
-  
+
   vsprintf (buf, fmt, args2);
-  
+
   fprintf(stderr,
-          "%s: %s\n", 
+          "%s: %s\n",
           title,buf);
 }
 
@@ -82,21 +82,24 @@ myXmlErrorReporting (void *ctx, const char* msg, ...)
 #endif
 
 /**
- * Basic (i.e. minimal) initialization of libdia. 
+ * libdia_init:
+ * @flags: a set of %DIA_INTERACTIVE, %DIA_MESSAGE_STDERR
+ *
+ * Basic (i.e. minimal) initialization of libdia.
  *
- * It does not load any plug-ins but instead brings libdia to a state that plug-in loading can take place.
- * @param flags a set of DIA_INTERACTIVE, DIA_MESSAGE_STDERR
+ * It does not load any plug-ins but instead brings libdia to a state that
+ * plug-in loading can take place.
  */
 void
 libdia_init (guint flags)
 {
   static gboolean initialized = FALSE;
-  
+
   if (initialized)
     return;
 
   if (flags & DIA_MESSAGE_STDERR)
-    set_message_func(stderr_message_internal);    
+    set_message_func(stderr_message_internal);
   LIBXML_TEST_VERSION;
 
 #ifdef G_OS_WIN32
diff --git a/lib/dialogs.c b/lib/dialogs.c
index 3e73a828..fa0af815 100644
--- a/lib/dialogs.c
+++ b/lib/dialogs.c
@@ -32,47 +32,74 @@
    meant to be transparent in that they don't make their own structures,
    they're just collections of common actions.
 */
-/** Creates a new dialog with a title and Ok and Cancel buttons.
-    Default texts are supplied for Ok and Cancel buttons if NULL.
-    Returns the created dialog and sets the two widget pointers.
-    This function does not call gtk_widget_show(), do
-    gtk_widget_show_all() when all has been added.
-*/
+
+/**
+ * dialog_make:
+ * @title: dialog title
+ * @okay_text: label for @okay_button
+ * @cancel_text: label of @cancel_button
+ * @okay_button: (out): the accept #GtkButton
+ * @cancel_button: (out): the reject #GtkButton
+ *
+ * Creates a new dialog with a title and Ok and Cancel buttons.
+ *
+ * Default texts are supplied for Ok and Cancel buttons if %NULL.
+ *
+ * This function does not call gtk_widget_show(), do
+ * gtk_widget_show_all() when all has been added.
+ *
+ * Returns: the created dialog and sets the two widget pointers.
+ */
 GtkWidget *
-dialog_make(char *title, char *okay_text, char *cancel_text,
-           GtkWidget **okay_button, GtkWidget **cancel_button) {
-  GtkWidget *dialog = gtk_dialog_new();
-  GtkWidget *label = gtk_label_new(title);
+dialog_make (char       *title,
+             char       *okay_text,
+             char       *cancel_text,
+             GtkWidget **okay_button,
+             GtkWidget **cancel_button)
+{
+  GtkWidget *dialog = gtk_dialog_new ();
+  GtkWidget *label = gtk_label_new (title);
 
-  gtk_container_add(GTK_CONTAINER(gtk_dialog_get_content_area(GTK_DIALOG(dialog))), label);
+  gtk_container_add (GTK_CONTAINER (gtk_dialog_get_content_area (GTK_DIALOG(dialog))), label);
 
-  *okay_button = gtk_button_new_with_label((okay_text!=NULL?okay_text:_("OK")));
-  *cancel_button = gtk_button_new_with_label((cancel_text!=NULL?cancel_text:_("Cancel")));
+  *okay_button = gtk_button_new_with_label ((okay_text != NULL ? okay_text : _("OK")));
+  *cancel_button = gtk_button_new_with_label ((cancel_text != NULL ? cancel_text : _("Cancel")));
 
-  gtk_container_add(GTK_CONTAINER(gtk_dialog_get_action_area(GTK_DIALOG(dialog))),
-                   *okay_button);
-  gtk_container_add(GTK_CONTAINER(gtk_dialog_get_action_area(GTK_DIALOG(dialog))),
-                   *cancel_button);
+  gtk_container_add (GTK_CONTAINER (gtk_dialog_get_action_area (GTK_DIALOG (dialog))),
+                     *okay_button);
+  gtk_container_add (GTK_CONTAINER (gtk_dialog_get_action_area (GTK_DIALOG(dialog))),
+                     *cancel_button);
 
   return dialog;
 }
 
-/** Adds a spinbutton with an attached label to a dialog.
-    To get an integer spinbutton, give decimals as 0.
+/**
+ * dialog_add_spinbutton:
+ * @dialog: the #GtkDialog
+ * @title: the spin box label
+ * @min: minimum value
+ * @max: the maximum value
+ * @decimals: how many digits
+ *
+ * Adds a spinbutton with an attached label to a dialog.
+ * To get an integer spinbutton, give decimals as 0.
 */
 GtkSpinButton *
-dialog_add_spinbutton(GtkWidget *dialog, char *title,
-                     real min, real max, real decimals) {
+dialog_add_spinbutton (GtkWidget *dialog,
+                       char      *title,
+                       real       min,
+                       real       max,
+                       real       decimals) {
   GtkAdjustment *limits =
-    GTK_ADJUSTMENT(gtk_adjustment_new(10.0, min, max, 1.0, 10.0, 0));
-  GtkWidget *box = gtk_hbox_new(FALSE, 10);
-  GtkWidget *label = gtk_label_new(title);
-  GtkWidget *entry = gtk_spin_button_new(limits, 10.0, decimals);
+    GTK_ADJUSTMENT (gtk_adjustment_new (10.0, min, max, 1.0, 10.0, 0));
+  GtkWidget *box = gtk_hbox_new (FALSE, 10);
+  GtkWidget *label = gtk_label_new (title);
+  GtkWidget *entry = gtk_spin_button_new (limits, 10.0, decimals);
 
-  gtk_box_pack_start (GTK_BOX(box), label, TRUE, TRUE, 0);
-  gtk_box_pack_start (GTK_BOX(box), entry, TRUE, TRUE, 0);
-  gtk_container_add(GTK_CONTAINER(gtk_dialog_get_content_area(GTK_DIALOG(dialog))), box);
+  gtk_box_pack_start (GTK_BOX (box), label, TRUE, TRUE, 0);
+  gtk_box_pack_start (GTK_BOX (box), entry, TRUE, TRUE, 0);
+  gtk_container_add (GTK_CONTAINER (gtk_dialog_get_content_area (GTK_DIALOG (dialog))), box);
 
-  return GTK_SPIN_BUTTON(entry);
+  return GTK_SPIN_BUTTON (entry);
 }
 
diff --git a/lib/filter.c b/lib/filter.c
index 4b69119f..b407db58 100644
--- a/lib/filter.c
+++ b/lib/filter.c
@@ -159,7 +159,11 @@ filter_guess_export_filter(const gchar *filename)
   return (no_guess == 1) ? dont_guess : NULL;
 }
 
-/** Get an export filter by unique name.
+/**
+ * filter_export_get_by_name:
+ * @name: the filter name
+ *
+ * Get an export filter by unique name.
  */
 DiaExportFilter *
 filter_export_get_by_name(const gchar *name)
diff --git a/lib/object_defaults.c b/lib/object_defaults.c
index b2759336..073915b0 100644
--- a/lib/object_defaults.c
+++ b/lib/object_defaults.c
@@ -79,11 +79,12 @@ _obj_destroy (gpointer val)
 }
 
 /**
- * @param filename the file to load from or NULL for default
- * @param create_lazy if FALSE creates default objects for
+ * dia_object_defaults_load:
+ * @filename: the file to load from or NULL for default
+ * @create_lazy: if %FALSE creates default objects for
  *             every known type. Otherwise default objects
  *             are created on demand
- * @param ctx The context in which this function is called
+ * @ctx: The context in which this function is called
  *
  * Create all the default objects.
  */
diff --git a/lib/persistence.c b/lib/persistence.c
index df977292..0a057976 100644
--- a/lib/persistence.c
+++ b/lib/persistence.c
@@ -234,7 +234,12 @@ persistence_load_color(gchar *role, xmlNodePtr node, DiaContext *ctx)
 
 static GHashTable *type_handlers;
 
-/** Load the named type of entries using the given function.
+/**
+ * persistence_load_type:
+ * @node:
+ * @ctx:
+ *
+ * Load the named type of entries using the given function.
  * func is a void (*func)(gchar *role, xmlNodePtr *node, DiaContext *ctx)
  */
 static void
diff --git a/lib/prop_text.c b/lib/prop_text.c
index 1828b49a..5dad072b 100644
--- a/lib/prop_text.c
+++ b/lib/prop_text.c
@@ -109,8 +109,8 @@ stringprop_set_from_widget(StringProperty *prop, GtkWidget *widget)
 static gboolean
 multistringprop_handle_key(GtkWidget *wid, GdkEventKey *event)
 {
-  /** Normal textview doesn't grab return, so to avoid closing the dialog...*/
-  /** Actually, this doesn't seem to work -- I guess the dialog closes
+  /* Normal textview doesn't grab return, so to avoid closing the dialog...*/
+  /* Actually, this doesn't seem to work -- I guess the dialog closes
    * becore this is called :(
    */
   if (event->keyval == GDK_Return)