Fix program messages and gtk-doc comments.

19 files changed, 317 insertions, 328 deletions

diff --git a/liblogdiag/ld-canvas.c b/liblogdiag/ld-canvas.c
index 3e7e8ed..779d92b 100644
--- a/liblogdiag/ld-canvas.c
+++ b/liblogdiag/ld-canvas.c
@@ -18,7 +18,7 @@
 
 /**
  * SECTION:ld-canvas
- * @short_description: A canvas.
+ * @short_description: A canvas
  * @see_also: #LdDiagram
  *
  * #LdCanvas displays and enables the user to manipulate with an #LdDiagram.
@@ -93,17 +93,17 @@ struct _LdCanvasColor
 
 /*
  * LdCanvasPrivate:
- * @diagram: A diagram object assigned to this canvas as a model.
- * @library: A library object assigned to this canvas as a model.
- * @adjustment_h: An adjustment object for the horizontal axis, if any.
- * @adjustment_v: An adjustment object for the vertical axis, if any.
- * @x: The X coordinate of the center of view.
- * @y: The Y coordinate of the center of view.
- * @zoom: The current zoom of the canvas.
- * @operation: The current operation.
- * @operation_data: Data related to the current operation.
- * @operation_end: A callback to end the operation.
- * @palette: Colors used by the widget.
+ * @diagram: a diagram object assigned to this canvas as a model.
+ * @library: a library object assigned to this canvas as a model.
+ * @adjustment_h: an adjustment object for the horizontal axis, if any.
+ * @adjustment_v: an adjustment object for the vertical axis, if any.
+ * @x: the X coordinate of the center of view.
+ * @y: the Y coordinate of the center of view.
+ * @zoom: the current zoom of the canvas.
+ * @operation: the current operation.
+ * @operation_data: data related to the current operation.
+ * @operation_end: a callback to end the operation.
+ * @palette: colors used by the widget.
  */
 struct _LdCanvasPrivate
 {
@@ -136,10 +136,10 @@ struct _LdCanvasPrivate
 
 /*
  * DrawData:
- * @self: Our #LdCanvas.
- * @cr: A cairo context to draw on.
- * @exposed_rect: The area that is to be redrawn.
- * @scale: Computed size of one diagram unit in pixels.
+ * @self: our #LdCanvas.
+ * @cr: a cairo context to draw on.
+ * @exposed_rect: the area that is to be redrawn.
+ * @scale: computed size of one diagram unit in pixels.
  */
 typedef struct _DrawData DrawData;
 
@@ -284,9 +284,9 @@ ld_canvas_class_init (LdCanvasClass *klass)
 
 /**
  * LdCanvas::set-scroll-adjustments:
- * @self: An #LdCanvas object.
- * @horizontal: The horizontal #GtkAdjustment.
- * @vertical: The vertical #GtkAdjustment.
+ * @self: an #LdCanvas object.
+ * @horizontal: the horizontal #GtkAdjustment.
+ * @vertical: the vertical #GtkAdjustment.
  *
  * Set scroll adjustments for the canvas.
  */
@@ -300,7 +300,7 @@ ld_canvas_class_init (LdCanvasClass *klass)
 
 /**
  * LdCanvas::cancel-operation:
- * @self: An #LdCanvas object.
+ * @self: an #LdCanvas object.
  *
  * Cancel any current operation.
  */
@@ -568,8 +568,8 @@ ld_canvas_new (void)
 
 /**
  * ld_canvas_set_diagram:
- * @self: An #LdCanvas object.
- * @diagram: The #LdDiagram to be assigned to the canvas.
+ * @self: an #LdCanvas object.
+ * @diagram: the #LdDiagram to be assigned to the canvas.
  *
  * Assign an #LdDiagram object to the canvas.
  */
@@ -594,7 +594,7 @@ ld_canvas_set_diagram (LdCanvas *self, LdDiagram *diagram)
 
 /**
  * ld_canvas_get_diagram:
- * @self: An #LdCanvas object.
+ * @self: an #LdCanvas object.
  *
  * Get the #LdDiagram object assigned to this canvas.
  * The reference count on the diagram is not incremented.
@@ -629,8 +629,8 @@ diagram_disconnect_signals (LdCanvas *self)
 
 /**
  * ld_canvas_set_library:
- * @self: An #LdCanvas object.
- * @library: The #LdLibrary to be assigned to the canvas.
+ * @self: an #LdCanvas object.
+ * @library: the #LdLibrary to be assigned to the canvas.
  *
  * Assign an #LdLibrary object to the canvas.
  */
@@ -651,7 +651,7 @@ ld_canvas_set_library (LdCanvas *self, LdLibrary *library)
 
 /**
  * ld_canvas_get_library:
- * @self: An #LdCanvas object.
+ * @self: an #LdCanvas object.
  *
  * Get the #LdLibrary object assigned to this canvas.
  * The reference count on the library is not incremented.
@@ -665,9 +665,9 @@ ld_canvas_get_library (LdCanvas *self)
 
 /*
  * ld_canvas_get_base_unit_in_px:
- * @self: A #GtkWidget object to retrieve DPI from (indirectly).
+ * @self: a #GtkWidget object to retrieve DPI from (indirectly).
  *
- * Return value: Length of the base unit in pixels.
+ * Return value: length of the base unit in pixels.
  */
 static gdouble
 ld_canvas_get_base_unit_in_px (GtkWidget *self)
@@ -686,9 +686,9 @@ ld_canvas_get_base_unit_in_px (GtkWidget *self)
 
 /*
  * ld_canvas_get_scale_in_px:
- * @self: An #LdCanvas object.
+ * @self: an #LdCanvas object.
  *
- * Return value: Displayed length of the base unit in pixels.
+ * Return value: displayed length of the base unit in pixels.
  */
 static gdouble
 ld_canvas_get_scale_in_px (LdCanvas *self)
@@ -701,11 +701,11 @@ ld_canvas_get_scale_in_px (LdCanvas *self)
 
 /**
  * ld_canvas_widget_to_diagram_coords:
- * @self: An #LdCanvas object.
- * @wx: The X coordinate to be translated.
- * @wy: The Y coordinate to be translated.
- * @dx: (out): The translated X coordinate.
- * @dy: (out): The translated Y coordinate.
+ * @self: an #LdCanvas object.
+ * @wx: the X coordinate to be translated.
+ * @wy: the Y coordinate to be translated.
+ * @dx: (out): the translated X coordinate.
+ * @dy: (out): the translated Y coordinate.
  *
  * Translate coordinates located inside the canvas window
  * into diagram coordinates.
@@ -734,11 +734,11 @@ ld_canvas_widget_to_diagram_coords (LdCanvas *self,
 
 /**
  * ld_canvas_diagram_to_widget_coords:
- * @self: An #LdCanvas object.
- * @dx: The X coordinate to be translated.
- * @dy: The Y coordinate to be translated.
- * @wx: (out): The translated X coordinate.
- * @wy: (out): The translated Y coordinate.
+ * @self: an #LdCanvas object.
+ * @dx: the X coordinate to be translated.
+ * @dy: the Y coordinate to be translated.
+ * @wx: (out): the translated X coordinate.
+ * @wy: (out): the translated Y coordinate.
  *
  * Translate diagram coordinates into canvas coordinates.
  */
@@ -763,9 +763,9 @@ ld_canvas_diagram_to_widget_coords (LdCanvas *self,
 
 /**
  * ld_canvas_get_zoom:
- * @self: An #LdCanvas object.
+ * @self: an #LdCanvas object.
  *
- * Return value: Zoom of the canvas.
+ * Return value: zoom of the canvas.
  */
 gdouble
 ld_canvas_get_zoom (LdCanvas *self)
@@ -776,8 +776,8 @@ ld_canvas_get_zoom (LdCanvas *self)
 
 /**
  * ld_canvas_set_zoom:
- * @self: An #LdCanvas object.
- * @zoom: The zoom.
+ * @self: an #LdCanvas object.
+ * @zoom: the zoom.
  *
  * Set zoom of the canvas.
  */
@@ -820,8 +820,8 @@ ld_canvas_real_cancel_operation (LdCanvas *self)
 
 /**
  * ld_canvas_add_object_begin:
- * @self: An #LdCanvas object.
- * @object: (transfer full): The object to be added to the diagram.
+ * @self: an #LdCanvas object.
+ * @object: (transfer full): the object to be added to the diagram.
  *
  * Begin an operation for adding an object into the diagram.
  */
@@ -1386,7 +1386,7 @@ draw_symbol (LdDiagramSymbol *diagram_symbol, DrawData *data)
 	/* TODO: Resolve this better; draw a cross or whatever. */
 	if (!symbol)
 	{
-		g_warning ("Cannot find symbol %s in the library.",
+		g_warning ("cannot find symbol `%s' in the library",
 			ld_diagram_symbol_get_class (diagram_symbol));
 		return;
 	}
diff --git a/liblogdiag/ld-canvas.h b/liblogdiag/ld-canvas.h
index a5b952b..b7e66d8 100644
--- a/liblogdiag/ld-canvas.h
+++ b/liblogdiag/ld-canvas.h
@@ -39,8 +39,6 @@ struct _LdCanvas
 /*< private >*/
 	GtkDrawingArea parent_instance;
 	LdCanvasPrivate *priv;
-
-/*< public >*/
 };
 
 struct _LdCanvasClass
@@ -57,7 +55,7 @@ struct _LdCanvasClass
 
 
 /**
- * LD_CANVAS_BASE_UNIT:
+ * LD_CANVAS_BASE_UNIT_LENGTH:
  *
  * Length of the base unit in milimetres.
  */
diff --git a/liblogdiag/ld-diagram-object.c b/liblogdiag/ld-diagram-object.c
index 754ab1d..166aed1 100644
--- a/liblogdiag/ld-diagram-object.c
+++ b/liblogdiag/ld-diagram-object.c
@@ -16,7 +16,7 @@
 
 /**
  * SECTION:ld-diagram-object
- * @short_description: A diagram object.
+ * @short_description: A diagram object
  * @see_also: #LdDiagram, #LdCanvas
  *
  * #LdDiagramObject represents an object in an #LdDiagram.
@@ -24,7 +24,7 @@
 
 /*
  * LdDiagramObjectPrivate:
- * @storage: Storage for object parameters.
+ * @storage: storage for object parameters.
  */
 struct _LdDiagramObjectPrivate
 {
@@ -93,10 +93,10 @@ ld_diagram_object_class_init (LdDiagramObjectClass *klass)
 
 /**
  * LdDiagramObject::data-changed:
- * @self: An #LdDiagramObject object.
- * @path: Path to the data.
- * @old_value: (allow-none): The old value of data.
- * @new_value: (allow-none): The new value of data.
+ * @self: an #LdDiagramObject object.
+ * @path: path to the data.
+ * @old_value: (allow-none): the old value of data.
+ * @new_value: (allow-none): the new value of data.
  *
  * Some data have been changed in internal storage.
  */
@@ -181,9 +181,9 @@ ld_diagram_object_dispose (GObject *gobject)
 
 /**
  * ld_diagram_object_new:
- * @storage: A storage backend.
+ * @storage: a storage backend.
  *
- * Return value: A new #LdDiagramObject object.
+ * Return value: a new #LdDiagramObject object.
  */
 LdDiagramObject *
 ld_diagram_object_new (JsonObject *storage)
@@ -196,11 +196,11 @@ ld_diagram_object_new (JsonObject *storage)
 
 /**
  * ld_diagram_object_get_storage:
- * @self: An #LdDiagramObject object.
+ * @self: an #LdDiagramObject object.
  *
  * Get the storage for object parameters.
  *
- * Return value: (transfer none): A #JsonObject boxed type.
+ * Return value: (transfer none): a #JsonObject boxed type.
  */
 JsonObject *
 ld_diagram_object_get_storage (LdDiagramObject *self)
@@ -213,8 +213,8 @@ ld_diagram_object_get_storage (LdDiagramObject *self)
 
 /**
  * ld_diagram_object_set_storage:
- * @self: An #LdDiagramObject object.
- * @storage: (transfer none): A #JsonObject boxed type.
+ * @self: an #LdDiagramObject object.
+ * @storage: (transfer none): a #JsonObject boxed type.
  *
  * Set the storage for object parameters.
  */
@@ -234,11 +234,11 @@ ld_diagram_object_set_storage (LdDiagramObject *self, JsonObject *storage)
 
 /**
  * ld_diagram_object_get_data:
- * @self: An #LdDiagramObject object.
- * @data: (out): An uninitialized storage for the data.
- * @type: Requested type of data. %G_TYPE_NONE for any.
- * @first_element: The first element of path to the data.
- * @...: Optional remaining elements, followed by %NULL.
+ * @self: an #LdDiagramObject object.
+ * @data: (out): an uninitialized storage for the data.
+ * @type: requested type of data. %G_TYPE_NONE for any.
+ * @first_element: the first element of path to the data.
+ * @...: optional remaining elements, followed by %NULL.
  *
  * Retrieve data from internal storage.
  *
@@ -260,10 +260,10 @@ ld_diagram_object_get_data (LdDiagramObject *self,
 
 /**
  * ld_diagram_object_set_data:
- * @self: An #LdDiagramObject object.
- * @data: (allow-none): The data. %NULL just removes the current data.
- * @first_element: The first element of path where the data will be stored.
- * @...: Optional remaining elements, followed by %NULL.
+ * @self: an #LdDiagramObject object.
+ * @data: (allow-none): the data. %NULL just removes the current data.
+ * @first_element: the first element of path where the data will be stored.
+ * @...: optional remaining elements, followed by %NULL.
  *
  * Put data into internal storage.
  */
@@ -280,11 +280,11 @@ ld_diagram_object_set_data (LdDiagramObject *self,
 
 /**
  * ld_diagram_object_get_data_valist:
- * @self: An #LdDiagramObject object.
- * @data: (out): An uninitialized storage for the data.
- * @type: Requested type of data. %G_TYPE_NONE for any.
- * @first_element: The first element of path to the data.
- * @var_args: Optional remaining elements, followed by %NULL.
+ * @self: an #LdDiagramObject object.
+ * @data: (out): an uninitialized storage for the data.
+ * @type: requested type of data. %G_TYPE_NONE for any.
+ * @first_element: the first element of path to the data.
+ * @var_args: optional remaining elements, followed by %NULL.
  *
  * Retrieve data from internal storage.
  *
@@ -305,10 +305,10 @@ ld_diagram_object_get_data_valist (LdDiagramObject *self,
 
 /**
  * ld_diagram_object_set_data_valist:
- * @self: An #LdDiagramObject object.
- * @data: (allow-none): The data. %NULL just removes the current data.
- * @first_element: The first element of path where the data will be stored.
- * @var_args: Optional remaining elements, followed by %NULL.
+ * @self: an #LdDiagramObject object.
+ * @data: (allow-none): the data. %NULL just removes the current data.
+ * @first_element: the first element of path where the data will be stored.
+ * @var_args: optional remaining elements, followed by %NULL.
  *
  * Put data into internal storage.
  */
@@ -344,10 +344,10 @@ args_to_strv (const gchar *first_arg, va_list args)
 
 /**
  * ld_diagram_object_get_datav:
- * @self: An #LdDiagramObject object.
- * @data: (out): An uninitialized storage for the data.
- * @type: Requested type of data. %G_TYPE_NONE for any.
- * @elements: An array of elements of path to the data, terminated by %NULL.
+ * @self: an #LdDiagramObject object.
+ * @data: (out): an uninitialized storage for the data.
+ * @type: requested type of data. %G_TYPE_NONE for any.
+ * @elements: an array of elements of path to the data, terminated by %NULL.
  *
  * Retrieve data from internal storage.
  *
@@ -411,9 +411,9 @@ ld_diagram_object_get_datav (LdDiagramObject *self,
 
 /**
  * ld_diagram_object_set_datav:
- * @self: An #LdDiagramObject object.
- * @data: (allow-none): The data. %NULL just removes the current data.
- * @elements: An array of elements of path where the data will be stored,
+ * @self: an #LdDiagramObject object.
+ * @data: (allow-none): the data. %NULL just removes the current data.
+ * @elements: an array of elements of path where the data will be stored,
  *            terminated by %NULL.
  *
  * Put data into internal storage.
@@ -489,9 +489,9 @@ void ld_diagram_object_set_datav (LdDiagramObject *self,
 
 /**
  * ld_diagram_object_get_data_for_param:
- * @self: An #LdDiagramObject object.
- * @data: (out): An uninitialized storage for the data.
- * @pspec: The parameter to read data for. This must be a property of @self.
+ * @self: an #LdDiagramObject object.
+ * @data: (out): an uninitialized storage for the data.
+ * @pspec: the parameter to read data for. This must be a property of @self.
  *
  * Retrieve data for a parameter from internal storage. If there's no data
  * corresponding to this parameter, the value is set to the default.
@@ -519,9 +519,9 @@ ld_diagram_object_get_data_for_param (LdDiagramObject *self,
 
 /**
  * ld_diagram_object_set_data_for_param:
- * @self: An #LdDiagramObject object.
- * @data: The data.
- * @pspec: The parameter to put data for.
+ * @self: an #LdDiagramObject object.
+ * @data: the data.
+ * @pspec: the parameter to put data for.
  *
  * Put data for a parameter into internal storage.
  */
@@ -542,9 +542,9 @@ ld_diagram_object_set_data_for_param (LdDiagramObject *self,
 
 /**
  * ld_diagram_object_get_x:
- * @self: An #LdDiagramObject object.
+ * @self: an #LdDiagramObject object.
  *
- * Return value: The X coordinate of the object.
+ * Return value: the X coordinate of the object.
  */
 gdouble
 ld_diagram_object_get_x (LdDiagramObject *self)
@@ -558,9 +558,9 @@ ld_diagram_object_get_x (LdDiagramObject *self)
 
 /**
  * ld_diagram_object_get_y:
- * @self: An #LdDiagramObject object.
+ * @self: an #LdDiagramObject object.
  *
- * Return value: The Y coordinate of the object.
+ * Return value: the Y coordinate of the object.
  */
 gdouble
 ld_diagram_object_get_y (LdDiagramObject *self)
@@ -574,8 +574,8 @@ ld_diagram_object_get_y (LdDiagramObject *self)
 
 /**
  * ld_diagram_object_set_x:
- * @self: An #LdDiagramObject object.
- * @x: The new X coordinate.
+ * @self: an #LdDiagramObject object.
+ * @x: the new X coordinate.
  *
  * Set the X coordinate of the object.
  */
@@ -588,8 +588,8 @@ ld_diagram_object_set_x (LdDiagramObject *self, gdouble x)
 
 /**
  * ld_diagram_object_set_y:
- * @self: An #LdDiagramObject object.
- * @y: The new Y coordinate.
+ * @self: an #LdDiagramObject object.
+ * @y: the new Y coordinate.
  *
  * Set the Y coordinate of the object.
  */
diff --git a/liblogdiag/ld-diagram-symbol.c b/liblogdiag/ld-diagram-symbol.c
index 9007938..f0a47e5 100644
--- a/liblogdiag/ld-diagram-symbol.c
+++ b/liblogdiag/ld-diagram-symbol.c
@@ -16,7 +16,7 @@
 
 /**
  * SECTION:ld-diagram-symbol
- * @short_description: A symbol object.
+ * @short_description: A symbol object
  * @see_also: #LdDiagramObject
  *
  * #LdDiagramSymbol is an implementation of #LdDiagramObject.
@@ -103,9 +103,9 @@ ld_diagram_symbol_set_property (GObject *object, guint property_id,
 
 /**
  * ld_diagram_symbol_new:
- * @storage: A storage backend.
+ * @storage: a storage backend.
  *
- * Return value: A new #LdDiagramSymbol object.
+ * Return value: a new #LdDiagramSymbol object.
  */
 LdDiagramSymbol *
 ld_diagram_symbol_new (JsonObject *storage)
@@ -118,9 +118,9 @@ ld_diagram_symbol_new (JsonObject *storage)
 
 /**
  * ld_diagram_symbol_get_class:
- * @self: An #LdDiagramSymbol object.
+ * @self: an #LdDiagramSymbol object.
  *
- * Return value: The class of the symbol.
+ * Return value: the class of the symbol.
  */
 const gchar *
 ld_diagram_symbol_get_class (LdDiagramSymbol *self)
@@ -134,8 +134,8 @@ ld_diagram_symbol_get_class (LdDiagramSymbol *self)
 
 /**
  * ld_diagram_symbol_set_class:
- * @self: An #LdDiagramSymbol object.
- * @klass: The class.
+ * @self: an #LdDiagramSymbol object.
+ * @klass: the class.
  *
  * Set the class of the symbol.
  */
diff --git a/liblogdiag/ld-diagram.c b/liblogdiag/ld-diagram.c
index 7f9bad7..1812eb0 100644
--- a/liblogdiag/ld-diagram.c
+++ b/liblogdiag/ld-diagram.c
@@ -14,7 +14,7 @@
 
 /**
  * SECTION:ld-diagram
- * @short_description: A diagram object.
+ * @short_description: A model for diagrams
  * @see_also: #LdCanvas
  *
  * #LdDiagram is a model used for storing diagrams.
@@ -22,10 +22,10 @@
 
 /*
  * LdDiagramPrivate:
- * @modified: Whether the diagram has been modified.
- * @objects: All objects in the diagram.
- * @selection: All currently selected objects.
- * @connections: Connections between objects.
+ * @modified: whether the diagram has been modified.
+ * @objects: all objects in the diagram.
+ * @selection: all currently selected objects.
+ * @connections: connections between objects.
  */
 struct _LdDiagramPrivate
 {
@@ -94,7 +94,7 @@ ld_diagram_class_init (LdDiagramClass *klass)
 
 /**
  * LdDiagram::changed:
- * @self: An #LdDiagram object.
+ * @self: an #LdDiagram object.
  *
  * Contents of the diagram have changed.
  */
@@ -106,7 +106,7 @@ ld_diagram_class_init (LdDiagramClass *klass)
 
 /**
  * LdDiagram::selection-changed:
- * @self: An #LdDiagram object.
+ * @self: an #LdDiagram object.
  *
  * The current selection has changed.
  */
@@ -193,7 +193,7 @@ ld_diagram_real_changed (LdDiagram *self)
  *
  * Registers an error quark for #LdDiagram if necessary.
  *
- * Return value: The error quark used for #LdDiagram errors.
+ * Return value: the error quark used for #LdDiagram errors.
  */
 GQuark
 ld_diagram_error_quark (void)
@@ -214,7 +214,7 @@ ld_diagram_new (void)
 
 /**
  * ld_diagram_clear:
- * @self: An #LdDiagram object.
+ * @self: an #LdDiagram object.
  *
  * Clear the whole diagram with it's objects and selection.
  */
@@ -233,7 +233,7 @@ ld_diagram_clear (LdDiagram *self)
 
 /*
  * ld_diagram_clear_internal:
- * @self: An #LdDiagram object.
+ * @self: an #LdDiagram object.
  *
  * Do the same as ld_diagram_clear() does but don't emit signals.
  */
@@ -252,13 +252,13 @@ ld_diagram_clear_internal (LdDiagram *self)
 
 /**
  * ld_diagram_load_from_file:
- * @self: An #LdDiagram object.
- * @filename: A filename.
- * @error: Return location for a GError, or NULL.
+ * @self: an #LdDiagram object.
+ * @filename: a filename.
+ * @error: (allow-none): return location for a #GError, or %NULL.
  *
  * Load a file into the diagram.
  *
- * Return value: TRUE if the file could be loaded, FALSE otherwise.
+ * Return value: %TRUE if the file could be loaded, %FALSE otherwise.
  */
 gboolean
 ld_diagram_load_from_file (LdDiagram *self,
@@ -296,13 +296,13 @@ ld_diagram_load_from_file (LdDiagram *self,
 
 /**
  * ld_diagram_save_to_file:
- * @self: An #LdDiagram object.
- * @filename: A filename.
- * @error: Return location for a GError, or NULL.
+ * @self: an #LdDiagram object.
+ * @filename: a filename.
+ * @error: (allow-none): return location for a #GError, or %NULL.
  *
  * Save the diagram into a file.
  *
- * Return value: TRUE if the diagram could be saved, FALSE otherwise.
+ * Return value: %TRUE if the diagram could be saved, %FALSE otherwise.
  */
 gboolean
 ld_diagram_save_to_file (LdDiagram *self,
@@ -503,9 +503,9 @@ get_object_class_string (GType type)
 
 /**
  * ld_diagram_get_modified:
- * @self: An #LdDiagram object.
+ * @self: an #LdDiagram object.
  *
- * Return value: The modification status of diagram.
+ * Return value: the modification status of diagram.
  */
 gboolean
 ld_diagram_get_modified (LdDiagram *self)
@@ -516,8 +516,8 @@ ld_diagram_get_modified (LdDiagram *self)
 
 /**
  * ld_diagram_set_modified:
- * @self: An #LdDiagram object.
- * @value: Whether the diagram has been modified.
+ * @self: an #LdDiagram object.
+ * @value: whether the diagram has been modified.
  *
  * Set the modification status of diagram.
  */
@@ -532,7 +532,7 @@ ld_diagram_set_modified (LdDiagram *self, gboolean value)
 
 /**
  * ld_diagram_get_objects:
- * @self: An #LdDiagram object.
+ * @self: an #LdDiagram object.
  *
  * Get a list of objects in the diagram. Do not modify.
  */
@@ -545,9 +545,9 @@ ld_diagram_get_objects (LdDiagram *self)
 
 /**
  * ld_diagram_insert_object:
- * @self: An #LdDiagram object.
- * @object: The object to be inserted.
- * @pos: The position at which the object is to be inserted.
+ * @self: an #LdDiagram object.
+ * @object: the object to be inserted.
+ * @pos: the position at which the object is to be inserted.
  *       Negative values will append to the end.
  *
  * Insert an object into the diagram.
@@ -571,8 +571,8 @@ ld_diagram_insert_object (LdDiagram *self, LdDiagramObject *object, gint pos)
 
 /**
  * ld_diagram_remove_object:
- * @self: An #LdDiagram object.
- * @object: The object to be removed.
+ * @self: an #LdDiagram object.
+ * @object: the object to be removed.
  *
  * Remove an object from the diagram.
  */
@@ -596,7 +596,7 @@ ld_diagram_remove_object (LdDiagram *self, LdDiagramObject *object)
 
 /**
  * ld_diagram_get_selection:
- * @self: An #LdDiagram object.
+ * @self: an #LdDiagram object.
  *
  * Get a list of objects that are currently selected in the diagram.
  * Do not modify.
@@ -610,7 +610,7 @@ ld_diagram_get_selection (LdDiagram *self)
 
 /**
  * ld_diagram_remove_selection:
- * @self: An #LdDiagram object.
+ * @self: an #LdDiagram object.
  *
  * Remove selected objects from the diagram.
  */
@@ -647,8 +647,8 @@ ld_diagram_remove_selection (LdDiagram *self)
 
 /**
  * ld_diagram_select:
- * @self: An #LdDiagram object.
- * @object: The object to be added to the selection.
+ * @self: an #LdDiagram object.
+ * @object: the object to be added to the selection.
  *
  * Add an object to selection.
  */
@@ -673,8 +673,8 @@ ld_diagram_select (LdDiagram *self, LdDiagramObject *object)
 
 /**
  * ld_diagram_unselect:
- * @self: An #LdDiagram object.
- * @object: The object to be removed from the selection.
+ * @self: an #LdDiagram object.
+ * @object: the object to be removed from the selection.
  *
  * Remove an object from the selection.
  */
@@ -696,7 +696,7 @@ ld_diagram_unselect (LdDiagram *self, LdDiagramObject *object)
 
 /**
  * ld_diagram_select_all:
- * @self: An #LdDiagram object.
+ * @self: an #LdDiagram object.
  *
  * Include all objects in the document to the selection.
  */
@@ -716,7 +716,7 @@ ld_diagram_select_all (LdDiagram *self)
 
 /**
  * ld_diagram_unselect_all:
- * @self: An #LdDiagram object.
+ * @self: an #LdDiagram object.
  *
  * Remove all objects from the current selection.
  */
diff --git a/liblogdiag/ld-library-toolbar.c b/liblogdiag/ld-library-toolbar.c
index 7ee983a..d1ceb9c 100644
--- a/liblogdiag/ld-library-toolbar.c
+++ b/liblogdiag/ld-library-toolbar.c
@@ -14,7 +14,7 @@
 
 /**
  * SECTION:ld-library-toolbar
- * @short_description: A library toolbar.
+ * @short_description: A library toolbar
  * @see_also: #LdLibrary
  *
  * #LdLibraryToolbar enables the user to choose symbols from an #LdLibrary.
@@ -70,10 +70,10 @@ enum
 
 /*
  * LdLibraryToolbarPrivate:
- * @library: A library object assigned to this canvas as a model.
- * @canvas: A canvas object for showing symbol menus.
- * @canvas_handlers: Signal handlers that hook the canvas.
- * @symbol_menu: Data related to menus.
+ * @library: a library object assigned to this canvas as a model.
+ * @canvas: a canvas object for showing symbol menus.
+ * @canvas_handlers: signal handlers that hook the canvas.
+ * @symbol_menu: data related to menus.
  */
 struct _LdLibraryToolbarPrivate
 {
@@ -157,9 +157,9 @@ ld_library_toolbar_class_init (LdLibraryToolbarClass *klass)
 
 /**
  * LdLibraryToolbar::symbol-chosen:
- * @self: An #LdLibraryToolbar object.
- * @symbol: The chosen #LdSymbol object.
- * @klass: Location of the symbol within the library.
+ * @self: an #LdLibraryToolbar object.
+ * @symbol: the chosen #LdSymbol object.
+ * @klass: location of the symbol within the library.
  *
  * A symbol has been chosen.
  */
@@ -172,9 +172,9 @@ ld_library_toolbar_class_init (LdLibraryToolbarClass *klass)
 
 /**
  * LdLibraryToolbar::symbol-selected:
- * @self: An #LdLibraryToolbar object.
- * @symbol: The selected #LdSymbol object.
- * @klass: Location of the symbol within the library.
+ * @self: an #LdLibraryToolbar object.
+ * @symbol: the selected #LdSymbol object.
+ * @klass: location of the symbol within the library.
  *
  * A symbol has been selected.
  */
@@ -187,9 +187,9 @@ ld_library_toolbar_class_init (LdLibraryToolbarClass *klass)
 
 /**
  * LdLibraryToolbar::symbol-deselected:
- * @self: An #LdLibraryToolbar object.
- * @symbol: The deselected #LdSymbol object.
- * @klass: Location of the symbol within the library.
+ * @self: an #LdLibraryToolbar object.
+ * @symbol: the deselected #LdSymbol object.
+ * @klass: location of the symbol within the library.
  *
  * A symbol has been deselected.
  */
@@ -280,8 +280,8 @@ ld_library_toolbar_new (void)
 
 /**
  * ld_library_toolbar_set_library:
- * @self: An #LdLibraryToolbar object.
- * @library: (allow-none): The #LdLibrary to be assigned to the toolbar.
+ * @self: an #LdLibraryToolbar object.
+ * @library: (allow-none): the #LdLibrary to be assigned to the toolbar.
  *
  * Assign an #LdLibrary object to the toolbar.
  */
@@ -313,7 +313,7 @@ ld_library_toolbar_set_library (LdLibraryToolbar *self, LdLibrary *library)
 
 /**
  * ld_library_toolbar_get_library:
- * @self: An #LdLibraryToolbar object.
+ * @self: an #LdLibraryToolbar object.
  *
  * Get the #LdLibrary object assigned to this toolbar.
  * The reference count on the library is not incremented.
@@ -327,8 +327,8 @@ ld_library_toolbar_get_library (LdLibraryToolbar *self)
 
 /**
  * ld_library_toolbar_set_canvas:
- * @self: An #LdLibraryToolbar object.
- * @canvas: (allow-none): The #LdCanvas to be assigned to the toolbar.
+ * @self: an #LdLibraryToolbar object.
+ * @canvas: (allow-none): the #LdCanvas to be assigned to the toolbar.
  *
  * Assign an #LdCanvas object to the toolbar.
  */
@@ -369,7 +369,7 @@ ld_library_toolbar_set_canvas (LdLibraryToolbar *self, LdCanvas *canvas)
 
 /**
  * ld_library_toolbar_get_canvas:
- * @self: An #LdLibraryToolbar object.
+ * @self: an #LdLibraryToolbar object.
  *
  * Get the #LdLibrary object assigned to this toolbar.
  * The reference count on the canvas is not incremented.
diff --git a/liblogdiag/ld-library.c b/liblogdiag/ld-library.c
index 0f82b5e..4a56929 100644
--- a/liblogdiag/ld-library.c
+++ b/liblogdiag/ld-library.c
@@ -16,7 +16,7 @@
 
 /**
  * SECTION:ld-library
- * @short_description: A symbol library.
+ * @short_description: A symbol library
  * @see_also: #LdSymbol, #LdSymbolCategory
  *
  * #LdLibrary is used for loading symbols from their files.
@@ -24,8 +24,8 @@
 
 /*
  * LdLibraryPrivate:
- * @lua: State of the scripting language.
- * @children: Child objects of the library.
+ * @lua: state of the scripting language.
+ * @children: child objects of the library.
  */
 struct _LdLibraryPrivate
 {
@@ -62,7 +62,7 @@ ld_library_class_init (LdLibraryClass *klass)
 
 /**
  * LdLibrary::changed:
- * @self: An #LdLibrary object.
+ * @self: an #LdLibrary object.
  *
  * Contents of the library have changed.
  */
@@ -158,9 +158,9 @@ LoadCategoryData;
 
 /*
  * load_category:
- * @self: An #LdLibrary object.
- * @path: The path to the category.
- * @name: The default name of the category.
+ * @self: an #LdLibrary object.
+ * @path: the path to the category.
+ * @name: the default name of the category.
  *
  * Loads a category into the library.
  */
@@ -182,7 +182,7 @@ load_category (LdLibrary *self, const gchar *path, const gchar *name)
 	icon_file = g_build_filename (path, "icon.svg", NULL);
 	if (!g_file_test (icon_file, G_FILE_TEST_IS_REGULAR))
 	{
-		g_warning ("The category in %s has no icon.", path);
+		g_warning ("the category in `%s' has no icon", path);
 		goto load_category_fail_2;
 	}
 
@@ -257,8 +257,8 @@ load_category_symbol_cb (LdSymbol *symbol, gpointer user_data)
 			continue;
 		if (!strcmp (name, ld_symbol_get_name (LD_SYMBOL (iter->data))))
 		{
-			g_warning ("Attempted to insert multiple '%s' symbols into"
-				" category '%s'.", name, ld_symbol_category_get_name (cat));
+			g_warning ("attempted to insert multiple `%s' symbols into"
+				" category `%s'", name, ld_symbol_category_get_name (cat));
 			return;
 		}
 	}
@@ -267,7 +267,7 @@ load_category_symbol_cb (LdSymbol *symbol, gpointer user_data)
 
 /*
  * read_human_name_from_file:
- * @filename: Location of the JSON file.
+ * @filename: location of the JSON file.
  *
  * Read the human name of the processed category.
  */
@@ -294,7 +294,7 @@ read_human_name_from_file (const gchar *filename)
 	root = json_parser_get_root (parser);
 	if (!JSON_NODE_HOLDS_OBJECT (root))
 	{
-		g_warning ("Failed to parse '%s': %s", filename,
+		g_warning ("failed to parse `%s': %s", filename,
 			"The root node is not an object.");
 		goto read_human_name_from_file_end;
 	}
@@ -337,8 +337,8 @@ LibraryLoadData;
 
 /**
  * ld_library_load:
- * @self: An #LdLibrary object.
- * @directory: A directory to be loaded.
+ * @self: an #LdLibrary object.
+ * @directory: a directory to be loaded.
  *
  * Load the contents of a directory into the library.
  */
@@ -387,12 +387,12 @@ ld_library_load_cb (const gchar *base, const gchar *filename, gpointer userdata)
 
 /**
  * ld_library_find_symbol:
- * @self: An #LdLibrary object.
- * @identifier: An identifier of the symbol to be searched for.
+ * @self: an #LdLibrary object.
+ * @identifier: an identifier of the symbol to be searched for.
  *
  * Search for a symbol in the library.
  *
- * Return value: A symbol object if found, NULL otherwise.
+ * Return value: a symbol object if found, %NULL otherwise.
  */
 /* XXX: With this level of indentation, this function is really ugly. */
 LdSymbol *
@@ -453,7 +453,7 @@ ld_library_find_symbol (LdLibrary *self, const gchar *identifier)
 
 /**
  * ld_library_clear:
- * @self: An #LdLibrary object.
+ * @self: an #LdLibrary object.
  *
  * Clear all the contents.
  */
@@ -472,9 +472,9 @@ ld_library_clear (LdLibrary *self)
 
 /**
  * ld_library_insert_child:
- * @self: An #LdLibrary object.
- * @child: The child to be inserted.
- * @pos: The position at which the child will be inserted.
+ * @self: an #LdLibrary object.
+ * @child: the child to be inserted.
+ * @pos: the position at which the child will be inserted.
  *       Negative values will append to the end of list.
  *
  * Insert a child into the library.
@@ -491,8 +491,8 @@ ld_library_insert_child (LdLibrary *self, GObject *child, gint pos)
 
 /**
  * ld_library_remove_child:
- * @self: An #LdLibrary object.
- * @child: The child to be removed.
+ * @self: an #LdLibrary object.
+ * @child: the child to be removed.
  *
  * Remove a child from the library.
  */
@@ -511,9 +511,9 @@ ld_library_remove_child (LdLibrary *self, GObject *child)
 
 /**
  * ld_library_get_children:
- * @self: An #LdLibrary object.
+ * @self: an #LdLibrary object.
  *
- * Return value: The internal list of children. Do not modify.
+ * Return value: the internal list of children. Do not modify.
  */
 const GSList *
 ld_library_get_children (LdLibrary *self)
diff --git a/liblogdiag/ld-lua-symbol-private.h b/liblogdiag/ld-lua-symbol-private.h
index 83bc646..f19a4a7 100644
--- a/liblogdiag/ld-lua-symbol-private.h
+++ b/liblogdiag/ld-lua-symbol-private.h
@@ -18,11 +18,11 @@ G_BEGIN_DECLS
 
 /*
  * LdLuaSymbolPrivate:
- * @lua: Parent #LdLua object.
- * @name: Name of this symbol.
- * @human_name: Localized human name of this symbol.
- * @area: Area of this symbol.
- * @terminals: Terminals of this symbol.
+ * @lua: parent #LdLua object.
+ * @name: name of this symbol.
+ * @human_name: localized human name of this symbol.
+ * @area: area of this symbol.
+ * @terminals: terminals of this symbol.
  */
 struct _LdLuaSymbolPrivate
 {
diff --git a/liblogdiag/ld-lua-symbol.c b/liblogdiag/ld-lua-symbol.c
index 27a6279..a7ad39e 100644
--- a/liblogdiag/ld-lua-symbol.c
+++ b/liblogdiag/ld-lua-symbol.c
@@ -17,7 +17,7 @@
 
 /**
  * SECTION:ld-lua-symbol
- * @short_description: A symbol.
+ * @short_description: A symbol
  * @see_also: #LdSymbol
  *
  * #LdLuaSymbol is an implementation of #LdSymbol.
diff --git a/liblogdiag/ld-lua-symbol.h b/liblogdiag/ld-lua-symbol.h
index 5f68b59..7d1f6f4 100644
--- a/liblogdiag/ld-lua-symbol.h
+++ b/liblogdiag/ld-lua-symbol.h
@@ -43,10 +43,10 @@ struct _LdLuaSymbol
 
 /**
  * LdLuaSymbolClass:
- * @parent_class: The parent class.
  */
 struct _LdLuaSymbolClass
 {
+/*< private >*/
 	LdSymbolClass parent_class;
 };
 
diff --git a/liblogdiag/ld-lua.c b/liblogdiag/ld-lua.c
index 47a41b5..973de4e 100644
--- a/liblogdiag/ld-lua.c
+++ b/liblogdiag/ld-lua.c
@@ -21,7 +21,7 @@
 
 /**
  * SECTION:ld-lua
- * @short_description: Lua symbol engine.
+ * @short_description: Lua symbol engine
  * @see_also: #LdLuaSymbol
  *
  * #LdLua is a symbol engine that uses Lua scripts to manage symbols.
@@ -50,9 +50,9 @@ struct _LdLuaPrivate
 
 /*
  * LdLuaData:
- * @self: A reference to self.
- * @load_callback: A callback for newly registered symbols.
- * @load_user_data: User data to be passed to the callback.
+ * @self: a reference to self.
+ * @load_callback: a callback for newly registered symbols.
+ * @load_user_data: user data to be passed to the callback.
  *
  * Full user data to be stored in Lua registry.
  */
@@ -232,8 +232,8 @@ ld_lua_alloc (void *ud, void *ptr, size_t osize, size_t nsize)
 
 /**
  * ld_lua_check_file:
- * @self: An #LdLua object.
- * @filename: The file to be checked.
+ * @self: an #LdLua object.
+ * @filename: the file to be checked.
  *
  * Check if the given filename can be loaded by #LdLua.
  */
@@ -249,15 +249,15 @@ ld_lua_check_file (LdLua *self, const gchar *filename)
 
 /**
  * ld_lua_load_file:
- * @self: An #LdLua object.
- * @filename: The file to be loaded.
- * @callback: A callback for newly registered symbols.
+ * @self: an #LdLua object.
+ * @filename: the file to be loaded.
+ * @callback: a callback for newly registered symbols.
  * The callee is responsible for referencing the symbol.
- * @user_data: User data to be passed to the callback.
+ * @user_data: user data to be passed to the callback.
  *
  * Loads a file and creates #LdLuaSymbol objects for contained symbols.
  *
- * Returns: TRUE if no error has occured, FALSE otherwise.
+ * Returns: %TRUE if no error has occured, %FALSE otherwise.
  */
 gboolean
 ld_lua_load_file (LdLua *self, const gchar *filename,
@@ -304,9 +304,9 @@ ld_lua_lftc_fail:
 
 /**
  * ld_lua_private_draw:
- * @self: An #LdLua object.
- * @symbol: A symbol to be drawn.
- * @cr: A Cairo context to be drawn onto.
+ * @self: an #LdLua object.
+ * @symbol: a symbol to be drawn.
+ * @cr: a Cairo context to be drawn onto.
  *
  * Draw a symbol onto a Cairo context.
  */
@@ -357,8 +357,8 @@ ld_lua_private_draw_cb (lua_State *L)
 
 /**
  * ld_lua_private_unregister:
- * @self: An #LdLua object.
- * @symbol: A symbol to be unregistered.
+ * @self: an #LdLua object.
+ * @symbol: a symbol to be unregistered.
  *
  * Unregister a symbol from the internal Lua state.
  */
@@ -437,7 +437,7 @@ ld_lua_logdiag_register (lua_State *L)
 
 /*
  * process_registration:
- * @L: A Lua state.
+ * @L: a Lua state.
  *
  * Parse arguments, write them to a symbol object and register the object.
  */
@@ -486,13 +486,13 @@ process_registration (lua_State *L)
 
 /*
  * get_translation:
- * @L: A Lua state.
- * @index: Stack index of the table.
+ * @L: a Lua state.
+ * @index: stack index of the table.
  *
  * Select an applicable translation from a table.
  * The return value has to be freed with g_free().
  *
- * Return value: The translation, if found. If none was found, returns NULL.
+ * Return value: the translation, if found. If none was found, returns %NULL.
  */
 static gchar *
 get_translation (lua_State *L, int index)
@@ -516,13 +516,13 @@ get_translation (lua_State *L, int index)
 
 /*
  * read_symbol_area:
- * @L: A Lua state.
- * @index: Stack index of the table.
- * @area: Where the area will be returned.
+ * @L: a Lua state.
+ * @index: stack index of the table.
+ * @area: where the area will be returned.
  *
  * Read a symbol area from a Lua table.
  *
- * Return value: TRUE on success, FALSE on failure.
+ * Return value: %TRUE on success, %FALSE on failure.
  */
 static gboolean
 read_symbol_area (lua_State *L, int index, LdRectangle *area)
@@ -563,13 +563,13 @@ read_symbol_area (lua_State *L, int index, LdRectangle *area)
 
 /*
  * read_terminals:
- * @L: A Lua state.
- * @index: Stack index of the table.
- * @area: Where the point array will be returned.
+ * @L: a Lua state.
+ * @index: stack index of the table.
+ * @area: where the point array will be returned.
  *
  * Read symbol terminals from a Lua table.
  *
- * Return value: TRUE on success, FALSE on failure.
+ * Return value: %TRUE on success, %FALSE on failure.
  */
 static gboolean
 read_terminals (lua_State *L, int index, LdPointArray **terminals)
diff --git a/liblogdiag/ld-lua.h b/liblogdiag/ld-lua.h
index b207d66..5e83626 100644
--- a/liblogdiag/ld-lua.h
+++ b/liblogdiag/ld-lua.h
@@ -48,8 +48,8 @@ struct _LdLuaClass
 
 /**
  * LdLuaLoadCallback:
- * @symbol: The symbol that has been created.
- * @user_data: User data passed to ld_lua_load_file().
+ * @symbol: the symbol that has been created.
+ * @user_data: user data passed to ld_lua_load_file().
  *
  * A callback function that is called when a symbol is created.
  */
diff --git a/liblogdiag/ld-symbol-category.c b/liblogdiag/ld-symbol-category.c
index e4b86a9..d4ac3cb 100644
--- a/liblogdiag/ld-symbol-category.c
+++ b/liblogdiag/ld-symbol-category.c
@@ -14,7 +14,7 @@
 
 /**
  * SECTION:ld-symbol-category
- * @short_description: A category of symbols.
+ * @short_description: A category of symbols
  * @see_also: #LdSymbol, #LdLibrary
  *
  * #LdSymbolCategory represents a category of #LdSymbol objects.
@@ -22,9 +22,9 @@
 
 /*
  * LdSymbolCategoryPrivate:
- * @name: The name of this category.
- * @image_path: Path to the image for this category.
- * @children: Children of this category.
+ * @name: the name of this category.
+ * @image_path: path to the image for this category.
+ * @children: children of this category.
  */
 struct _LdSymbolCategoryPrivate
 {
@@ -172,8 +172,8 @@ ld_symbol_category_finalize (GObject *gobject)
 
 /**
  * ld_symbol_category_new:
- * @name: The name of the new category.
- * @human_name: The localized human name of the new category.
+ * @name: the name of the new category.
+ * @human_name: the localized human name of the new category.
  *
  * Create an instance.
  */
@@ -194,8 +194,8 @@ ld_symbol_category_new (const gchar *name, const gchar *human_name)
 
 /**
  * ld_symbol_category_set_name:
- * @self: An #LdSymbolCategory object.
- * @name: The new name for this category.
+ * @self: an #LdSymbolCategory object.
+ * @name: the new name for this category.
  */
 void
 ld_symbol_category_set_name (LdSymbolCategory *self, const gchar *name)
@@ -212,7 +212,7 @@ ld_symbol_category_set_name (LdSymbolCategory *self, const gchar *name)
 
 /**
  * ld_symbol_category_get_name:
- * @self: An #LdSymbolCategory object.
+ * @self: an #LdSymbolCategory object.
  *
  * Return the name of this category.
  */
@@ -225,8 +225,8 @@ ld_symbol_category_get_name (LdSymbolCategory *self)
 
 /**
  * ld_symbol_category_set_human_name:
- * @self: An #LdSymbolCategory object.
- * @human_name: The new localized human name for this category.
+ * @self: an #LdSymbolCategory object.
+ * @human_name: the new localized human name for this category.
  */
 void
 ld_symbol_category_set_human_name (LdSymbolCategory *self,
@@ -244,7 +244,7 @@ ld_symbol_category_set_human_name (LdSymbolCategory *self,
 
 /**
  * ld_symbol_category_get_human_name:
- * @self: An #LdSymbolCategory object.
+ * @self: an #LdSymbolCategory object.
  *
  * Return the localized human name of this category.
  */
@@ -257,8 +257,8 @@ ld_symbol_category_get_human_name (LdSymbolCategory *self)
 
 /**
  * ld_symbol_category_set_image_path:
- * @self: An #LdSymbolCategory object.
- * @image_path: The new path to the image for this category. May be NULL.
+ * @self: an #LdSymbolCategory object.
+ * @image_path: (allow-none): The new path to the image for this category.
  */
 void
 ld_symbol_category_set_image_path (LdSymbolCategory *self,
@@ -275,9 +275,9 @@ ld_symbol_category_set_image_path (LdSymbolCategory *self,
 
 /**
  * ld_symbol_category_get_image_path:
- * @self: An #LdSymbolCategory object.
+ * @self: an #LdSymbolCategory object.
  *
- * Return the filesystem path to the image for this category. May be NULL.
+ * Return value: (allow-none): filesystem path to the image for this category.
  */
 const gchar *
 ld_symbol_category_get_image_path (LdSymbolCategory *self)
@@ -288,9 +288,9 @@ ld_symbol_category_get_image_path (LdSymbolCategory *self)
 
 /**
  * ld_symbol_category_insert_child:
- * @self: An #LdSymbolCategory object.
- * @child: The child to be inserted.
- * @pos: The position at which the child will be inserted.
+ * @self: an #LdSymbolCategory object.
+ * @child: the child to be inserted.
+ * @pos: the position at which the child will be inserted.
  *       Negative values will append to the end of list.
  *
  * Insert a child into the category.
@@ -308,8 +308,8 @@ ld_symbol_category_insert_child (LdSymbolCategory *self,
 
 /**
  * ld_symbol_category_remove_child:
- * @self: An #LdSymbolCategory object.
- * @child: The child to be removed.
+ * @self: an #LdSymbolCategory object.
+ * @child: the child to be removed.
  *
  * Removes a child from the category.
  */
@@ -326,9 +326,9 @@ ld_symbol_category_remove_child (LdSymbolCategory *self,
 
 /**
  * ld_symbol_category_get_children:
- * @self: An #LdSymbolCategory object.
+ * @self: an #LdSymbolCategory object.
  *
- * Return value: The internal list of children. Do not modify.
+ * Return value: the internal list of children. Do not modify.
  */
 const GSList *
 ld_symbol_category_get_children (LdSymbolCategory *self)
diff --git a/liblogdiag/ld-symbol.c b/liblogdiag/ld-symbol.c
index fafa9ab..bcc68d9 100644
--- a/liblogdiag/ld-symbol.c
+++ b/liblogdiag/ld-symbol.c
@@ -14,7 +14,7 @@
 
 /**
  * SECTION:ld-symbol
- * @short_description: A symbol.
+ * @short_description: A symbol
  * @see_also: #LdDiagramSymbol, #LdCanvas
  *
  * #LdSymbol represents a symbol to be drawn onto a #LdCanvas.
@@ -137,9 +137,9 @@ ld_symbol_set_property (GObject *object, guint property_id,
 
 /**
  * ld_symbol_get_name:
- * @self: An #LdSymbol object.
+ * @self: an #LdSymbol object.
  *
- * Return value: The name of the symbol.
+ * Return value: the name of the symbol.
  */
 const gchar *
 ld_symbol_get_name (LdSymbol *self)
@@ -155,9 +155,9 @@ ld_symbol_get_name (LdSymbol *self)
 
 /**
  * ld_symbol_get_human_name:
- * @self: An #LdSymbol object.
+ * @self: an #LdSymbol object.
  *
- * Return value: The localised human name of the symbol.
+ * Return value: the localised human name of the symbol.
  */
 const gchar *
 ld_symbol_get_human_name (LdSymbol *self)
@@ -173,8 +173,8 @@ ld_symbol_get_human_name (LdSymbol *self)
 
 /**
  * ld_symbol_get_area:
- * @self: An #LdSymbol object.
- * @area: Where the area of the symbol will be returned.
+ * @self: an #LdSymbol object.
+ * @area: where the area of the symbol will be returned.
  *
  * Get the area of the symbol.
  */
@@ -193,11 +193,11 @@ ld_symbol_get_area (LdSymbol *self, LdRectangle *area)
 
 /**
  * ld_symbol_get_terminals:
- * @self: An #LdSymbol object.
+ * @self: an #LdSymbol object.
  *
  * Get a list of symbol terminals.
  *
- * Return value: An #LdPointArray structure.
+ * Return value: an #LdPointArray structure.
  */
 const LdPointArray *
 ld_symbol_get_terminals (LdSymbol *self)
@@ -213,8 +213,8 @@ ld_symbol_get_terminals (LdSymbol *self)
 
 /**
  * ld_symbol_draw:
- * @self: An #LdSymbol object.
- * @cr: A cairo surface to be drawn on.
+ * @self: an #LdSymbol object.
+ * @cr: a cairo surface to be drawn on.
  *
  * Draw the symbol onto a Cairo surface.
  */
diff --git a/liblogdiag/ld-symbol.h b/liblogdiag/ld-symbol.h
index 409eba5..6151b58 100644
--- a/liblogdiag/ld-symbol.h
+++ b/liblogdiag/ld-symbol.h
@@ -40,17 +40,18 @@ struct _LdSymbol
 
 /**
  * LdSymbolClass:
- * @parent_class: The parent class.
- * @get_name: Get the name of the symbol.
- * @get_human_name: Get the localized human name of the symbol.
- * @get_area: Get the area of the symbol.
- * @get_terminals: Get a list of symbol terminals.
- * @draw: Draw the symbol on a Cairo surface.
+ * @get_name: get the name of the symbol.
+ * @get_human_name: get the localized human name of the symbol.
+ * @get_area: get the area of the symbol.
+ * @get_terminals: get a list of symbol terminals.
+ * @draw: draw the symbol on a Cairo surface.
  */
 struct _LdSymbolClass
 {
+/*< private >*/
 	GObjectClass parent_class;
 
+/*< public >*/
 	const gchar *(*get_name) (LdSymbol *self);
 	const gchar *(*get_human_name) (LdSymbol *self);
 	void (*get_area) (LdSymbol *self, LdRectangle *area);
diff --git a/liblogdiag/ld-types.c b/liblogdiag/ld-types.c
index cde3da6..c5723a9 100644
--- a/liblogdiag/ld-types.c
+++ b/liblogdiag/ld-types.c
@@ -14,6 +14,17 @@
 #include "config.h"
 
 
+/**
+ * SECTION:ld-types
+ * @short_description: Simple data types
+ *
+ * #LdPoint defines coordinates of a point.
+ *
+ * #LdPointArray defines an array of points.
+ *
+ * #LdRectangle defines the position and size of a rectangle.
+ */
+
 #define DEFINE_BOXED_TYPE(TypeName, type_name) \
 GType \
 type_name ## _get_type (void) \
@@ -52,18 +63,18 @@ type_name ## _free (TypeName *self) \
 
 /**
  * ld_point_copy:
- * @self: An #LdPoint structure.
+ * @self: an #LdPoint structure.
  *
  * Makes a copy of the structure.
  * The result must be freed by ld_point_free().
  *
- * Return value: A copy of @self.
+ * Return value: a copy of @self.
  */
 DEFINE_BOXED_TRIVIAL_COPY (LdPoint, ld_point)
 
 /**
  * ld_point_free:
- * @self: An #LdPoint structure.
+ * @self: an #LdPoint structure.
  *
  * Frees the structure created with ld_point_copy().
  */
@@ -71,9 +82,9 @@ DEFINE_BOXED_TRIVIAL_FREE (LdPoint, ld_point)
 
 /**
  * ld_point_distance:
- * @self: An #LdPoint structure.
- * @x: The X coordinate of the second point.
- * @y: The Y coordinate of the second point.
+ * @self: an #LdPoint structure.
+ * @x: the X coordinate of the second point.
+ * @y: the Y coordinate of the second point.
  *
  * Compute the distance between two points.
  */
@@ -91,11 +102,11 @@ ld_point_distance (LdPoint *self, gdouble x, gdouble y)
 
 /**
  * ld_point_array_new:
- * @num_points: The number of points the array can store.
+ * @num_points: the number of points the array can store.
  *
  * Create a new array of points and initialize.
  *
- * Return value: An #LdPointArray structure.
+ * Return value: an #LdPointArray structure.
  */
 LdPointArray *
 ld_point_array_new (gint num_points)
@@ -112,12 +123,12 @@ ld_point_array_new (gint num_points)
 
 /**
  * ld_point_array_copy:
- * @self: An #LdPointArray structure.
+ * @self: an #LdPointArray structure.
  *
  * Makes a copy of the structure.
  * The result must be freed by ld_point_array_free().
  *
- * Return value: A copy of @self.
+ * Return value: a copy of @self.
  */
 LdPointArray *
 ld_point_array_copy (const LdPointArray *self)
@@ -135,7 +146,7 @@ ld_point_array_copy (const LdPointArray *self)
 
 /**
  * ld_point_array_free:
- * @self: An #LdPointArray structure.
+ * @self: an #LdPointArray structure.
  *
  * Frees the structure created with ld_point_array_copy().
  */
@@ -150,18 +161,18 @@ ld_point_array_free (LdPointArray *self)
 
 /**
  * ld_rectangle_copy:
- * @self: An #LdRectangle structure.
+ * @self: an #LdRectangle structure.
  *
  * Makes a copy of the structure.
  * The result must be freed by ld_rectangle_free().
  *
- * Return value: A copy of @self.
+ * Return value: a copy of @self.
  */
 DEFINE_BOXED_TRIVIAL_COPY (LdRectangle, ld_rectangle)
 
 /**
  * ld_rectangle_free:
- * @self: An #LdRectangle structure.
+ * @self: an #LdRectangle structure.
  *
  * Frees the structure created with ld_rectangle_copy().
  */
@@ -169,11 +180,11 @@ DEFINE_BOXED_TRIVIAL_FREE (LdRectangle, ld_rectangle)
 
 /**
  * ld_rectangle_contains:
- * @self: An #LdRectangle structure.
- * @x: The X coordinate of the point to be checked.
- * @y: The Y coordinate of the point to be checked.
+ * @self: an #LdRectangle structure.
+ * @x: the X coordinate of the point to be checked.
+ * @y: the Y coordinate of the point to be checked.
  *
- * Return value: TRUE if the rectangle contains the specified point.
+ * Return value: %TRUE if the rectangle contains the specified point.
  */
 gboolean
 ld_rectangle_contains (LdRectangle *self, gdouble x, gdouble y)
@@ -185,10 +196,10 @@ ld_rectangle_contains (LdRectangle *self, gdouble x, gdouble y)
 
 /**
  * ld_rectangle_intersects:
- * @self: An #LdRectangle structure.
- * @rect: An #LdRectangle to be checked for intersection.
+ * @self: an #LdRectangle structure.
+ * @rect: an #LdRectangle to be checked for intersection.
  *
- * Return value: TRUE if the two rectangles intersect.
+ * Return value: %TRUE if the two rectangles intersect.
  */
 gboolean
 ld_rectangle_intersects (LdRectangle *self, LdRectangle *rect)
@@ -204,8 +215,8 @@ ld_rectangle_intersects (LdRectangle *self, LdRectangle *rect)
 
 /**
  * ld_rectangle_extend:
- * @self: An #LdRectangle structure.
- * @border: The border by which the rectangle should be extended.
+ * @self: an #LdRectangle structure.
+ * @border: the border by which the rectangle should be extended.
  *
  * Extend a rectangle on all sides.
  */
diff --git a/liblogdiag/ld-types.h b/liblogdiag/ld-types.h
index 61a1a7d..04fedfa 100644
--- a/liblogdiag/ld-types.h
+++ b/liblogdiag/ld-types.h
@@ -14,15 +14,6 @@
 G_BEGIN_DECLS
 
 
-/**
- * SECTION:ld-types
- * @short_description: Simple data types.
- *
- * #LdPoint defines coordinates of a point.
- *
- * #LdRectangle defines the position and size of a rectangle.
- */
-
 #define LD_TYPE_POINT (ld_point_get_type ())
 #define LD_TYPE_POINT_ARRAY (ld_point_array_get_type ())
 #define LD_TYPE_RECTANGLE (ld_rectangle_get_type ())
@@ -34,8 +25,8 @@ typedef struct _LdRectangle LdRectangle;
 
 /**
  * LdPoint:
- * @x: The X coordinate.
- * @y: The Y coordinate.
+ * @x: the X coordinate.
+ * @y: the Y coordinate.
  *
  * Defines a point.
  */
@@ -53,10 +44,10 @@ gdouble ld_point_distance (LdPoint *self, gdouble x, gdouble y);
 
 /**
  * LdPointArray:
- * @points: An array of #LdPoint structures.
- * @num_points: Count of points in @points.
+ * @points: an array of #LdPoint structures.
+ * @num_points: count of points in @points.
  *
- * Moves quickly.
+ * Defines an array of points.
  */
 struct _LdPointArray
 {
@@ -73,10 +64,10 @@ void ld_point_array_free (LdPointArray *self);
 
 /**
  * LdRectangle:
- * @x: Left-top X coordinate.
- * @y: Left-top Y coordinate.
- * @width: Width of the area, must be positive.
- * @height: Height of the area, must be positive.
+ * @x: left-top X coordinate.
+ * @y: left-top Y coordinate.
+ * @width: width of the area, must be positive.
+ * @height: height of the area, must be positive.
  *
  * Defines a rectangle.
  */
diff --git a/src/ld-window-main.c b/src/ld-window-main.c
index d59d2fd..f7d9f8d 100644
--- a/src/ld-window-main.c
+++ b/src/ld-window-main.c
@@ -16,13 +16,6 @@
 #include "ld-window-main.h"
 
 
-/**
- * SECTION:ld-window-main
- * @short_description: The main application window.
- *
- * #LdWindowMain is the main window of the application.
- */
-
 struct _LdWindowMainPrivate
 {
 	GtkUIManager *ui_manager;
@@ -361,7 +354,7 @@ update_title (LdWindowMain *self)
 
 /*
  * action_set_sensitive:
- * @sensitive: The sensitivity state.
+ * @sensitive: the sensitivity state.
  *
  * Set sensitivity of an action.
  */
@@ -461,7 +454,7 @@ diagram_get_name (LdWindowMain *self)
 
 /*
  * diagram_set_filename:
- * @filename: The new filename. May be NULL for a new, yet unsaved, file.
+ * @filename: (allow-none): the new filename. %NULL for a new file.
  *
  * Set the filename corresponding to the currently opened diagram.
  * The function takes ownership of the string.
@@ -524,7 +517,7 @@ diagram_save (LdWindowMain *self)
 	{
 		GtkWidget *message_dialog;
 
-		g_warning ("Saving failed: %s", error->message);
+		g_warning ("saving failed: %s", error->message);
 		g_error_free (error);
 
 		message_dialog = gtk_message_dialog_new (GTK_WINDOW (self),
@@ -546,7 +539,7 @@ diagram_save (LdWindowMain *self)
 /*
  * diagram_get_file_filter:
  *
- * Return value: A new #GtkFileFilter object for diagrams.
+ * Return value: a new #GtkFileFilter object for diagrams.
  */
 static GtkFileFilter *
 diagram_get_file_filter (void)
@@ -596,7 +589,7 @@ diagram_show_open_dialog (LdWindowMain *self)
 		{
 			GtkWidget *message_dialog;
 
-			g_warning ("Loading failed: %s", error->message);
+			g_warning ("loading failed: %s", error->message);
 			g_error_free (error);
 
 			message_dialog = gtk_message_dialog_new (GTK_WINDOW (self),
@@ -649,15 +642,15 @@ diagram_show_save_as_dialog (LdWindowMain *self)
 
 /*
  * may_close_diagram:
- * @dialog_message: The dialog message to display to the user if the diagram
+ * @dialog_message: the dialog message to display to the user if the diagram
  *                  has been modified.
  *
  * When no changes have been made to the current diagram, the function
  * lets the caller proceed. Otherwise the user is asked for further actions.
  * If he chooses to save the diagram, the function will handle this action.
  *
- * Return value: FALSE if the current action should be cancelled.
- *               TRUE if the caller may proceed.
+ * Return value: %FALSE if the current action should be cancelled.
+ *               %TRUE if the caller may proceed.
  */
 static gboolean
 may_close_diagram (LdWindowMain *self, const gchar *dialog_message)
@@ -714,7 +707,7 @@ may_close_diagram (LdWindowMain *self, const gchar *dialog_message)
  * A variant on may_close_diagram() for the occasion of closing
  * the whole application.
  *
- * Return value: TRUE if the application may quit, FALSE otherwise.
+ * Return value: %TRUE if the application may quit, %FALSE otherwise.
  */
 static gboolean
 may_quit (LdWindowMain *self)
diff --git a/src/ld-window-main.h b/src/ld-window-main.h
index df65a9b..8d28150 100644
--- a/src/ld-window-main.h
+++ b/src/ld-window-main.h
@@ -31,11 +31,6 @@ typedef struct _LdWindowMainPrivate LdWindowMainPrivate;
 typedef struct _LdWindowMainClass LdWindowMainClass;
 
 
-/**
- * LdWindowMain:
- *
- * Object structure.
- */
 struct _LdWindowMain
 {
 /*< private >*/