Fix comments.

7 files changed, 31 insertions, 29 deletions

diff --git a/src/ld-canvas.c b/src/ld-canvas.c
index 2ea676a..c12c2c2 100644
--- a/src/ld-canvas.c
+++ b/src/ld-canvas.c
@@ -37,7 +37,7 @@
 /* The default screen resolution in DPI units. */
 #define DEFAULT_SCREEN_RESOLUTION 96
 
-/* When requesting drawing, extend all sides of
+/* When drawing is requested, extend all sides of
  * the rectangle to be drawn by this number of pixels.
  */
 #define QUEUE_DRAW_EXTEND 3
@@ -501,7 +501,7 @@ on_size_allocate (GtkWidget *widget, GtkAllocation *allocation,
 	/* FIXME: If the new allocation is bigger, we may see more than
 	 *        what we're supposed to be able to see -> adjust X and Y.
 	 *
-	 *        If the visible area is just so large that we must see more,
+	 *        If the visible area is so large that we simply must see more,
 	 *        let's disable the scrollbars in question.
 	 */
 	update_adjustments (self);
@@ -647,7 +647,7 @@ ld_canvas_get_library (LdCanvas *self)
  * ld_canvas_get_base_unit_in_px:
  * @self: A #GtkWidget object to retrieve DPI from (indirectly).
  *
- * Return value: The 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)
@@ -668,7 +668,7 @@ ld_canvas_get_base_unit_in_px (GtkWidget *self)
  * ld_canvas_get_scale_in_px:
  * @self: An #LdCanvas object.
  *
- * Return value: The 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)
diff --git a/src/ld-canvas.h b/src/ld-canvas.h
index 74b3c33..3bbcac6 100644
--- a/src/ld-canvas.h
+++ b/src/ld-canvas.h
@@ -59,7 +59,7 @@ struct _LdCanvasClass
 /**
  * LD_CANVAS_BASE_UNIT:
  *
- * The length of the base unit in milimetres.
+ * Length of the base unit in milimetres.
  */
 #define LD_CANVAS_BASE_UNIT_LENGTH 2.5
 
diff --git a/src/ld-diagram.c b/src/ld-diagram.c
index 07070f1..49bfc9e 100644
--- a/src/ld-diagram.c
+++ b/src/ld-diagram.c
@@ -22,13 +22,13 @@
  * @short_description: A diagram object.
  * @see_also: #LdCanvas
  *
- * #LdDiagram is a model for storing diagrams.
+ * #LdDiagram is a model used for storing diagrams.
  */
 
 /*
  * LdDiagramPrivate:
  * @modified: Whether the diagram has been modified.
- * @objects: All the objects in the diagram.
+ * @objects: All objects in the diagram.
  * @selection: All currently selected objects.
  * @connections: Connections between objects.
  */
@@ -213,7 +213,7 @@ ld_diagram_clear (LdDiagram *self)
  * ld_diagram_clear_internal:
  * @self: An #LdDiagram object.
  *
- * Do the same what ld_diagram_clear() does but don't emit signals.
+ * Do the same as ld_diagram_clear() does but don't emit signals.
  */
 static void
 ld_diagram_clear_internal (LdDiagram *self)
@@ -340,8 +340,7 @@ ld_diagram_set_modified (LdDiagram *self, gboolean value)
  * ld_diagram_get_objects:
  * @self: An #LdDiagram object.
  *
- * Get a list of objects in the diagram.
- * You mustn't make any changes to the list.
+ * Get a list of objects in the diagram. Do not modify.
  */
 GList *
 ld_diagram_get_objects (LdDiagram *self)
@@ -406,7 +405,7 @@ ld_diagram_remove_object (LdDiagram *self, LdDiagramObject *object)
  * @self: An #LdDiagram object.
  *
  * Get a list of objects that are currently selected in the diagram.
- * You mustn't make any changes to the list.
+ * Do not modify.
  */
 GList *
 ld_diagram_get_selection (LdDiagram *self)
diff --git a/src/ld-library.c b/src/ld-library.c
index 5e4d502..debd0e2 100644
--- a/src/ld-library.c
+++ b/src/ld-library.c
@@ -168,7 +168,7 @@ LoadCategoryData;
 
 /*
  * load_category:
- * @self: A symbol library object.
+ * @self: An #LdLibrary object.
  * @path: The path to the category.
  * @name: The default name of the category.
  *
@@ -277,7 +277,7 @@ load_category_symbol_cb (LdSymbol *symbol, gpointer user_data)
 
 /*
  * read_human_name_from_file:
- * @filename: Where the JSON file is located.
+ * @filename: Location of the JSON file.
  *
  * Read the human name of the processed category.
  */
@@ -347,7 +347,7 @@ LibraryLoadData;
 
 /**
  * ld_library_load:
- * @self: A symbol library object.
+ * @self: An #LdLibrary object.
  * @directory: A directory to be loaded.
  *
  * Load the contents of a directory into the library.
@@ -397,7 +397,7 @@ ld_library_load_cb (const gchar *base, const gchar *filename, gpointer userdata)
 
 /**
  * ld_library_find_symbol:
- * @self: A symbol library object.
+ * @self: An #LdLibrary object.
  * @identifier: An identifier of the symbol to be searched for.
  *
  * Search for a symbol in the library.
@@ -463,9 +463,9 @@ ld_library_find_symbol (LdLibrary *self, const gchar *identifier)
 
 /**
  * ld_library_clear:
- * @self: A symbol library object.
+ * @self: An #LdLibrary object.
  *
- * Clears all the contents.
+ * Clear all the contents.
  */
 void
 ld_library_clear (LdLibrary *self)
@@ -504,7 +504,7 @@ ld_library_insert_child (LdLibrary *self, GObject *child, gint pos)
  * @self: An #LdLibrary object.
  * @child: The child to be removed.
  *
- * Removes a child from the library.
+ * Remove a child from the library.
  */
 void
 ld_library_remove_child (LdLibrary *self, GObject *child)
diff --git a/src/ld-lua.c b/src/ld-lua.c
index 47f2a40..7976606 100644
--- a/src/ld-lua.c
+++ b/src/ld-lua.c
@@ -46,9 +46,9 @@ struct _LdLuaPrivate
 };
 
 /* registry.logdiag_symbols
- *   -> table indexed by pointers to LdLuaSymbol objects
+ *   -> A table indexed by pointers to LdLuaSymbol objects
  * registry.logdiag_symbols.object.render(cr)
- *   -> rendering function
+ *   -> The rendering function
  */
 
 #define LD_LUA_LIBRARY_NAME "logdiag"
@@ -197,7 +197,7 @@ ld_lua_init (LdLua *self)
 
 	lua_setfield (L, LUA_REGISTRYINDEX, LD_LUA_DATA_INDEX);
 
-	/* Create an empty symbols table. */
+	/* Create an empty symbol table. */
 	lua_newtable (L);
 	lua_setfield (L, LUA_REGISTRYINDEX, LD_LUA_SYMBOLS_INDEX);
 }
@@ -633,7 +633,11 @@ push_cairo_object (lua_State *L, LdLuaDrawData *draw_data)
 	/* XXX: The light user data pointer gets invalid after the end of
 	 *      "render" function invocation. If the script stores the "cr" object
 	 *      in some global variable and then tries to reuse it the next time,
-	 *      the application will go SIGSEGV.
+	 *      the application may go SIGSEGV.
+	 *
+	 *      The solution is creating a full user data instead, referencing
+	 *      the cairo object and dereferencing it upon garbage collection
+	 *      of the user data object.
 	 */
 	for (fn = ld_lua_cairo_table; fn->name; fn++)
 	{
diff --git a/src/ld-symbol.c b/src/ld-symbol.c
index cdc59f5..fd9ef5a 100644
--- a/src/ld-symbol.c
+++ b/src/ld-symbol.c
@@ -21,10 +21,9 @@
 /**
  * SECTION:ld-symbol
  * @short_description: A symbol.
- * @see_also: #LdDiagram, #LdCanvas
+ * @see_also: #LdDiagramSymbol, #LdCanvas
  *
- * #LdSymbol represents a symbol in the #LdDiagram that is in turn
- * drawn onto the #LdCanvas.
+ * #LdSymbol represents a symbol to be drawn onto a #LdCanvas.
  *
  * All implementations of this abstract class are required to use
  * cairo_save() and cairo_restore() when drawing to store the state.
@@ -180,7 +179,7 @@ ld_symbol_get_human_name (LdSymbol *self)
 
 /**
  * ld_symbol_get_area:
- * @self: A symbol object.
+ * @self: An #LdSymbol object.
  * @area: Where the area of the symbol will be returned.
  *
  * Get the area of the symbol.
@@ -200,7 +199,7 @@ ld_symbol_get_area (LdSymbol *self, LdRectangle *area)
 
 /**
  * ld_symbol_get_terminals:
- * @self: A symbol object.
+ * @self: An #LdSymbol object.
  *
  * Get a list of symbol terminals.
  *
@@ -220,7 +219,7 @@ ld_symbol_get_terminals (LdSymbol *self)
 
 /**
  * ld_symbol_draw:
- * @self: A symbol object.
+ * @self: An #LdSymbol object.
  * @cr: A cairo surface to be drawn on.
  *
  * Draw the symbol onto a Cairo surface.
diff --git a/src/ld-window-main.c b/src/ld-window-main.c
index 2ea06b5..4ba86b3 100644
--- a/src/ld-window-main.c
+++ b/src/ld-window-main.c
@@ -743,7 +743,7 @@ on_canvas_button_press (GtkWidget *widget, GdkEventButton *event,
 	self = LD_WINDOW_MAIN (user_data);
 	data = &self->priv->symbol_menu;
 
-	/* The event occured elsewhere, cancel the menu and put the event
+	/* If the event occured elsewhere, cancel the menu and put the event
 	 * back into the queue.
 	 */
 	if (widget->window != event->window && data->active_button)