From 138cbaa02fe4b020622cb3cf3db5dc75dcfb0527 Mon Sep 17 00:00:00 2001
From: Nick Treleaven <nick.treleaven@btinternet.com>
Date: Fri, 12 Mar 2010 18:15:48 +0000
Subject: [PATCH] Use 3rd person (gets not get) for API function brief
 descriptions. Avoid using 'convenience function' in API brief descriptions.

git-svn-id: https://geany.svn.sourceforge.net/svnroot/geany/trunk@4757 ea778897-0a13-0410-b9d1-a72fbfd435f5
---
 ChangeLog          |  6 ++++
 src/document.c     |  2 +-
 src/document.h     |  6 ++--
 src/editor.c       | 10 +++---
 src/editor.h       |  2 +-
 src/filetypes.c    |  2 +-
 src/filetypes.h    |  2 +-
 src/highlighting.c |  4 +--
 src/keybindings.c  |  6 ++--
 src/plugindata.h   |  4 +--
 src/pluginutils.c  |  8 ++---
 src/sciwrappers.c  | 84 +++++++++++++++++++++++-----------------------
 src/ui_utils.c     | 19 +++++------
 src/ui_utils.h     |  2 +-
 src/utils.c        | 14 ++++----
 src/utils.h        |  6 ++--
 16 files changed, 91 insertions(+), 86 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index b7949e50..6f3d24c3 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -17,6 +17,12 @@
  * src/project.c:
    Make Long Line Marker settings for existing projects default to
    general settings instead of 0 (thanks to Eugene Arshinov).
+ * src/utils.c, src/ui_utils.h, src/utils.h, src/highlighting.c,
+   src/keybindings.c, src/sciwrappers.c, src/plugindata.h,
+   src/filetypes.c, src/filetypes.h, src/document.c, src/pluginutils.c,
+   src/document.h, src/editor.c, src/editor.h, src/ui_utils.c:
+   Use 3rd person (gets not get) for API function brief descriptions.
+   Avoid using 'convenience function' in API brief descriptions.
 
 
 2010-03-10  Nick Treleaven  <nick(dot)treleaven(at)btinternet(dot)com>
diff --git a/src/document.c b/src/document.c
index c8b2803a..b7064d7d 100644
--- a/src/document.c
+++ b/src/document.c
@@ -221,7 +221,7 @@ GeanyDocument *document_find_by_sci(ScintillaObject *sci)
 }
 
 
-/** Get the notebook page index for a document.
+/** Gets the notebook page index for a document.
  * @param doc The document.
  * @return The index.
  * @since 0.19 */
diff --git a/src/document.h b/src/document.h
index f2791d5e..2669489f 100644
--- a/src/document.h
+++ b/src/document.h
@@ -109,7 +109,7 @@ struct GeanyDocument
 extern GPtrArray *documents_array;
 
 
-/** Wrap documents_array so it can be used with C array syntax.
+/** Wraps documents_array so it can be used with C array syntax.
  * Example: documents[0]->sci = NULL;
  * @see document_index(). */
 #define documents ((GeanyDocument **)GEANY(documents_array)->pdata)
@@ -140,8 +140,8 @@ extern GPtrArray *documents_array;
 	(G_LIKELY((doc_ptr) != NULL) && G_LIKELY((doc_ptr)->is_valid))
 
 /**
- *  DOC_FILENAME returns the filename of the document passed or
- *  GEANY_STRING_UNTITLED (e.g. _("untitled")) if the document's filename was not yet set.
+ *  Returns the filename of the document passed or @c GEANY_STRING_UNTITLED
+ *  (e.g. _("untitled")) if the document's filename was not yet set.
  *  This macro never returns @c NULL.
  **/
 #define DOC_FILENAME(doc) \
diff --git a/src/editor.c b/src/editor.c
index 97837f01..dc7b898f 100644
--- a/src/editor.c
+++ b/src/editor.c
@@ -1026,7 +1026,7 @@ get_default_indent_prefs(void)
 }
 
 
-/** Get the indentation prefs for the editor.
+/** Gets the indentation prefs for the editor.
  * In future, the prefs might be different according to project or filetype.
  * @warning Always get a fresh result instead of keeping a pointer to it if the editor
  * settings may have changed, or if this function has been called for a different @a editor.
@@ -2095,7 +2095,7 @@ static void fix_line_indents(GeanyEditor *editor, gint line_start, gint line_end
 }
 
 /* TODO: Fix \\t inside comment*/
-/** Insert text, replacing \\t tab chars with the correct indent width, and \\n newline
+/** Inserts text, replacing \\t tab chars with the correct indent width, and \\n newline
  * chars with the correct line ending string.
  * @param editor The editor to operate on.
  * @param text Intended as e.g. "if (1)\n\tdo_something();"
@@ -4474,7 +4474,7 @@ void editor_set_line_wrapping(GeanyEditor *editor, gboolean wrap)
 }
 
 
-/** Set the indent type for @a editor.
+/** Sets the indent type for @a editor.
  * @param editor Editor.
  * @param type Indent type.
  *
@@ -4699,7 +4699,7 @@ static ScintillaObject *create_new_sci(GeanyEditor *editor)
 }
 
 
-/** Create a new Scintilla @c GtkWidget based on the settings for @a editor.
+/** Creates a new Scintilla @c GtkWidget based on the settings for @a editor.
  * @param editor Editor settings.
  * @return The new widget.
  *
@@ -4803,7 +4803,7 @@ void editor_init(void)
 }
 
 
-/** TODO: Should these be user-defined instead of hard-coded? */
+/* TODO: Should these be user-defined instead of hard-coded? */
 void editor_set_indentation_guides(GeanyEditor *editor)
 {
 	gint mode;
diff --git a/src/editor.h b/src/editor.h
index 38f8e9df..9c2ea88f 100644
--- a/src/editor.h
+++ b/src/editor.h
@@ -28,7 +28,7 @@
 #include "Scintilla.h"
 #include "ScintillaWidget.h"
 
-/** Default character set to define which characters shoud be treated as part of a word. */
+/** Default character set to define which characters should be treated as part of a word. */
 #define GEANY_WORDCHARS					"_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
 #define GEANY_MAX_WORD_LENGTH			192
 
diff --git a/src/filetypes.c b/src/filetypes.c
index 52dcc14b..de94adae 100644
--- a/src/filetypes.c
+++ b/src/filetypes.c
@@ -1447,7 +1447,7 @@ gboolean filetype_has_tags(GeanyFiletype *ft)
 }
 
 
-/** Find a filetype pointer from its @a name field.
+/** Finds a filetype pointer from its @a name field.
  * @param name Filetype name.
  * @return The filetype found, or @c NULL.
  *
diff --git a/src/filetypes.h b/src/filetypes.h
index 7e1a115e..ffcdfcd5 100644
--- a/src/filetypes.h
+++ b/src/filetypes.h
@@ -145,7 +145,7 @@ struct GeanyFiletype
 
 extern GPtrArray *filetypes_array;
 
-/** Wrap filetypes_array so it can be used with C array syntax.
+/** Wraps filetypes_array so it can be used with C array syntax.
  * Example: filetypes[GEANY_FILETYPES_C]->name = ...;
  * @see filetypes_index(). */
 #define filetypes	((GeanyFiletype **)GEANY(filetypes_array)->pdata)
diff --git a/src/highlighting.c b/src/highlighting.c
index 5d7c2f71..97af24e1 100644
--- a/src/highlighting.c
+++ b/src/highlighting.c
@@ -3196,7 +3196,7 @@ void highlighting_init_styles(gint filetype_idx, GKeyFile *config, GKeyFile *con
 		styleset_func(sci, ft->id); \
 		break
 
-/** Setup highlighting and other visual settings.
+/** Sets up highlighting and other visual settings.
  * @param sci Scintilla widget.
  * @param ft Filetype settings to use. */
 void highlighting_set_styles(ScintillaObject *sci, GeanyFiletype *ft)
@@ -3267,7 +3267,7 @@ void highlighting_set_styles(ScintillaObject *sci, GeanyFiletype *ft)
 }
 
 
-/** Retrieve a style @a style_id for the filetype @a ft_id.
+/** Retrieves a style @a style_id for the filetype @a ft_id.
  * If the style was not already initialised
  * (e.g. by by opening a file of this type), it will be initialised. The returned pointer is
  * owned by Geany and must not be freed.
diff --git a/src/keybindings.c b/src/keybindings.c
index 2645f3ea..6bed8f77 100644
--- a/src/keybindings.c
+++ b/src/keybindings.c
@@ -111,7 +111,7 @@ static void cb_func_move_tab(guint key_id);
 static void add_popup_menu_accels(void);
 
 
-/** Lookup a keybinding item.
+/** Looks up a keybinding item.
  * @param group Group.
  * @param key_id Keybinding index for the group.
  * @return The keybinding.
@@ -126,7 +126,7 @@ GeanyKeyBinding *keybindings_get_item(GeanyKeyGroup *group, gsize key_id)
 
 /* This is used to set default keybindings on startup.
  * Menu accels are set in apply_kb_accel(). */
-/** Simple convenience function to fill a GeanyKeyBinding struct item.
+/** Fills a GeanyKeyBinding struct item.
  * @param group Group.
  * @param key_id Keybinding index for the group.
  * @param callback Function to call when activated, or @c NULL to use the group callback.
@@ -1295,7 +1295,7 @@ GeanyKeyBinding *keybindings_lookup_item(guint group_id, guint key_id)
 }
 
 
-/** Mimic a (built-in only) keybinding action.
+/** Mimics a (built-in only) keybinding action.
  * 	Example: @code keybindings_send_command(GEANY_KEY_GROUP_FILE, GEANY_KEYS_FILE_OPEN); @endcode
  * 	@param group_id The index for the key group that contains the @a key_id keybinding.
  * 	@param key_id The keybinding command index. */
diff --git a/src/plugindata.h b/src/plugindata.h
index 185043c6..df261b27 100644
--- a/src/plugindata.h
+++ b/src/plugindata.h
@@ -59,7 +59,7 @@ enum {
 	GEANY_ABI_VERSION = 66
 };
 
-/** Check the plugin can be loaded by Geany.
+/** Checks the plugin can be loaded by Geany.
  * This performs runtime checks that try to ensure:
  * - Geany ABI data types are compatible with this plugin.
  * - Geany sources provide the required API for this plugin. */
@@ -101,7 +101,7 @@ typedef struct GeanyPlugin
 GeanyPlugin;
 
 
-/** Set the plugin name and some other basic information about a plugin.
+/** Sets the plugin name and some other basic information about a plugin.
  * This declares a function, so you can use the _() translation macro for arguments.
  *
  * Example:
diff --git a/src/pluginutils.c b/src/pluginutils.c
index 11eed1e8..e18c705c 100644
--- a/src/pluginutils.c
+++ b/src/pluginutils.c
@@ -40,7 +40,7 @@
 #include "plugins.h"
 
 
-/** Insert a toolbar item before the Quit button, or after the previous plugin toolbar item.
+/** Inserts a toolbar item before the Quit button, or after the previous plugin toolbar item.
  * A separator is added on the first call to this function, and will be shown when @a item is
  * shown; hidden when @a item is hidden.
  * @note You should still destroy @a item yourself, usually in @ref plugin_cleanup().
@@ -98,7 +98,7 @@ void plugin_module_make_resident(GeanyPlugin *plugin)
 }
 
 
-/** Connect a signal which will be disconnected on unloading the plugin, to prevent a possible segfault.
+/** Connects a signal which will be disconnected on unloading the plugin, to prevent a possible segfault.
  * @param plugin Must be @ref geany_plugin.
  * @param object Object to connect to, or @c NULL when using @link signals Geany signals @endlink.
  * @param signal_name The name of the signal. For a list of available
@@ -131,7 +131,7 @@ void plugin_signal_connect(GeanyPlugin *plugin,
 }
 
 
-/** Setup or resize a keybinding group for the plugin.
+/** Sets up or resizes a keybinding group for the plugin.
  * You should then call keybindings_set_item() for each keybinding in the group.
  * @param plugin Must be @ref geany_plugin.
  * @param section_name Name used in the configuration file, such as @c "html_chars".
@@ -246,7 +246,7 @@ static void configure_plugins(Plugin *current_plugin)
 }
 
 
-/** Show the plugin's configure dialog.
+/** Shows the plugin's configure dialog.
  * The plugin must implement one of the plugin_configure() or plugin_configure_single() symbols.
  * @param plugin Must be @ref geany_plugin.
  * @since 0.19. */
diff --git a/src/sciwrappers.c b/src/sciwrappers.c
index a0ff29f9..3c56acfc 100644
--- a/src/sciwrappers.c
+++ b/src/sciwrappers.c
@@ -176,7 +176,7 @@ void sci_add_text(ScintillaObject *sci, const gchar *text)
 }
 
 
-/** Set all text.
+/** Sets all text.
  * @param sci Scintilla widget.
  * @param text Text. */
 void sci_set_text(ScintillaObject *sci, const gchar *text)
@@ -213,7 +213,7 @@ void sci_redo(ScintillaObject *sci)
 }
 
 
-/** Begin grouping a set of edits together as one Undo action.
+/** Begins grouping a set of edits together as one Undo action.
  * You must call sci_end_undo_action() after making your edits.
  * @param sci Scintilla @c GtkWidget. */
 void sci_start_undo_action(ScintillaObject *sci)
@@ -222,7 +222,7 @@ void sci_start_undo_action(ScintillaObject *sci)
 }
 
 
-/** End grouping a set of edits together as one Undo action.
+/** Ends grouping a set of edits together as one Undo action.
  * @param sci Scintilla @c GtkWidget.
  * @see sci_start_undo_action(). */
 void sci_end_undo_action(ScintillaObject *sci)
@@ -273,7 +273,7 @@ gint sci_get_zoom(ScintillaObject *sci)
 }
 
 
-/** Set a line marker.
+/** Sets a line marker.
  * @param sci Scintilla widget.
  * @param line_number Line number.
  * @param marker Marker number. */
@@ -283,7 +283,7 @@ void sci_set_marker_at_line(ScintillaObject *sci, gint line_number, gint marker)
 }
 
 
-/** Delete a line marker.
+/** Deletes a line marker.
  * @param sci Scintilla widget.
  * @param line_number Line number.
  * @param marker Marker number. */
@@ -293,7 +293,7 @@ void sci_delete_marker_at_line(ScintillaObject *sci, gint line_number, gint mark
 }
 
 
-/** Check if a line has a marker set.
+/** Checks if a line has a marker set.
  * @param sci Scintilla widget.
  * @param line Line number.
  * @param marker Marker number.
@@ -351,7 +351,7 @@ gint sci_marker_previous(ScintillaObject *sci, gint line, gint marker_mask, gboo
 }
 
 
-/** Get line number from position.
+/** Gets the line number from @a position.
  * @param sci Scintilla widget.
  * @param position Position. */
 gint sci_get_line_from_position(ScintillaObject *sci, gint position)
@@ -360,7 +360,7 @@ gint sci_get_line_from_position(ScintillaObject *sci, gint position)
 }
 
 
-/** Get column number relative to the start of the line that @a position is on.
+/** Gets the column number relative to the start of the line that @a position is on.
  * @param sci Scintilla widget.
  * @param position Position. */
 gint sci_get_col_from_position(ScintillaObject *sci, gint position)
@@ -369,7 +369,7 @@ gint sci_get_col_from_position(ScintillaObject *sci, gint position)
 }
 
 
-/** Get position for the start of @a line.
+/** Gets the position for the start of @a line.
  * @param sci Scintilla widget.
  * @param line Line.
  * @return Position. */
@@ -379,7 +379,7 @@ gint sci_get_position_from_line(ScintillaObject *sci, gint line)
 }
 
 
-/** Get cursor position.
+/** Gets the cursor position.
  * @param sci Scintilla widget.
  * @return Position. */
 gint sci_get_current_position(ScintillaObject *sci)
@@ -388,7 +388,7 @@ gint sci_get_current_position(ScintillaObject *sci)
 }
 
 
-/** Set the cursor position.
+/** Sets the cursor position.
  * @param sci Scintilla widget.
  * @param position Position.
  * @param scroll_to_caret Whether to scroll the cursor in view. */
@@ -414,7 +414,7 @@ void sci_set_current_line(ScintillaObject *sci, gint line)
 }
 
 
-/** Get total number of lines.
+/** Gets the total number of lines.
  * @param sci Scintilla widget. */
 gint sci_get_line_count(ScintillaObject *sci)
 {
@@ -422,7 +422,7 @@ gint sci_get_line_count(ScintillaObject *sci)
 }
 
 
-/** Set selection start position.
+/** Sets the selection start position.
  * @param sci Scintilla widget.
  * @param position Position. */
 void sci_set_selection_start(ScintillaObject *sci, gint position)
@@ -431,7 +431,7 @@ void sci_set_selection_start(ScintillaObject *sci, gint position)
 }
 
 
-/** Set selection end position.
+/** Sets the selection end position.
  * @param sci Scintilla widget.
  * @param position Position. */
 void sci_set_selection_end(ScintillaObject *sci, gint position)
@@ -476,7 +476,7 @@ void sci_clear(ScintillaObject *sci)
 }
 
 
-/** Get position of selection start.
+/** Gets the selection start position.
  * @param sci Scintilla widget.
  * @return Position. */
 gint sci_get_selection_start(ScintillaObject *sci)
@@ -485,7 +485,7 @@ gint sci_get_selection_start(ScintillaObject *sci)
 }
 
 
-/** Get position of selection end.
+/** Gets the selection end position.
  * @param sci Scintilla widget.
  * @return Position. */
 gint sci_get_selection_end(ScintillaObject *sci)
@@ -494,7 +494,7 @@ gint sci_get_selection_end(ScintillaObject *sci)
 }
 
 
-/** Replace selection.
+/** Replaces selection.
  * @param sci Scintilla widget.
  * @param text Text. */
 void sci_replace_sel(ScintillaObject *sci, const gchar *text)
@@ -503,7 +503,7 @@ void sci_replace_sel(ScintillaObject *sci, const gchar *text)
 }
 
 
-/** Get length of all text.
+/** Gets the length of all text.
  * @param sci Scintilla widget.
  * @return Length. */
 gint sci_get_length(ScintillaObject *sci)
@@ -518,7 +518,7 @@ gint sci_get_lexer(ScintillaObject *sci)
 }
 
 
-/** Get line length.
+/** Gets line length.
  * @param sci Scintilla widget.
  * @param line Line number.
  * @return Length. */
@@ -541,7 +541,7 @@ gchar *sci_get_string(ScintillaObject *sci, gint msg, gulong wParam)
 }
 
 
-/** Get line contents.
+/** Gets line contents.
  * @param sci Scintilla widget.
  * @param line_num Line number.
  * @return A @c NULL-terminated copy of the line text. */
@@ -551,7 +551,7 @@ gchar *sci_get_line(ScintillaObject *sci, gint line_num)
 }
 
 
-/** Get all text.
+/** Gets all text.
  * @deprecated sci_get_text is deprecated and should not be used in newly-written code.
  * Use sci_get_contents() instead.
  *
@@ -564,7 +564,7 @@ void sci_get_text(ScintillaObject *sci, gint len, gchar *text)
 }
 
 
-/** Get all text inside a given text length.
+/** Gets all text inside a given text length.
  * @param sci Scintilla widget.
  * @param len Length of the text to retrieve from the start of the document,
  *            usually sci_get_length() + 1.
@@ -580,7 +580,7 @@ gchar *sci_get_contents(ScintillaObject *sci, gint len)
 }
 
 
-/** Get selected text.
+/** Gets selected text.
  * @deprecated sci_get_selected_text is deprecated and should not be used in newly-written code.
  * Use sci_get_selection_contents() instead.
  *
@@ -593,7 +593,7 @@ void sci_get_selected_text(ScintillaObject *sci, gchar *text)
 }
 
 
-/** Get selected text.
+/** Gets selected text.
  * @param sci Scintilla widget.
  *
  * @return The selected text. Should be freed when no longer needed.
@@ -606,7 +606,7 @@ gchar *sci_get_selection_contents(ScintillaObject *sci)
 }
 
 
-/** Get selected text length.
+/** Gets selected text length.
  * @param sci Scintilla widget.
  * @return Length. */
 gint sci_get_selected_text_length(ScintillaObject *sci)
@@ -622,7 +622,7 @@ gint sci_get_position_from_xy(ScintillaObject *sci, gint x, gint y, gboolean nea
 }
 
 
-/** Check if a line is visible (folding may have hidden it).
+/** Checks if a line is visible (folding may have hidden it).
  * @param sci Scintilla widget.
  * @param line Line number.
  * @return Whether @a line will be drawn on the screen. */
@@ -632,7 +632,7 @@ gboolean sci_get_line_is_visible(ScintillaObject *sci, gint line)
 }
 
 
-/** Make the @a line visible (folding may have hidden it).
+/** Makes @a line visible (folding may have hidden it).
  * @param sci Scintilla widget.
  * @param line Line number. */
 void sci_ensure_line_is_visible(ScintillaObject *sci, gint line)
@@ -690,7 +690,7 @@ void sci_set_tab_width(ScintillaObject *sci, gint width)
 }
 
 
-/** Get display tab width (this is not indent width, see GeanyIndentPrefs).
+/** Gets display tab width (this is not indent width, see GeanyIndentPrefs).
  * @param sci Scintilla widget.
  * @return Width.
  *
@@ -702,7 +702,7 @@ gint sci_get_tab_width(ScintillaObject *sci)
 }
 
 
-/** Get character.
+/** Gets a character.
  * @param sci Scintilla widget.
  * @param pos Position.
  * @return Char. */
@@ -730,7 +730,7 @@ void sci_use_popup(ScintillaObject *sci, gboolean enable)
 }
 
 
-/** Check if there's a selection.
+/** Checks if there's a selection.
  * @param sci Scintilla widget.
  * @return Whether a selection is present.
  *
@@ -768,7 +768,7 @@ void sci_set_anchor(ScintillaObject *sci, gint pos)
 }
 
 
-/** Scroll the cursor in view.
+/** Scrolls the cursor in view.
  * @param sci Scintilla widget. */
 void sci_scroll_caret(ScintillaObject *sci)
 {
@@ -800,7 +800,7 @@ gint sci_search_prev(ScintillaObject *sci, gint flags, const gchar *text)
 }
 
 
-/** Find a text in the document.
+/** Finds text in the document.
  * The @a ttf argument should be a pointer to a Sci_TextToFind structure which contains
  * the text to find and the range in which the text should be searched.
  *
@@ -826,7 +826,7 @@ void sci_set_font(ScintillaObject *sci, gint style, const gchar *font, gint size
 }
 
 
-/** Jump to the specified line in the document.
+/** Jumps to the specified line in the document.
  * If @a unfold is set and @a line is hidden by a fold, it is unfolded
  * first to ensure it is visible.
  * @param sci Scintilla widget.
@@ -846,7 +846,7 @@ void sci_marker_delete_all(ScintillaObject *sci, gint marker)
 }
 
 
-/** Get style ID for @a position.
+/** Gets style ID at @a position.
  * @param sci Scintilla widget.
  * @param position Position.
  * @return Style ID. */
@@ -875,7 +875,7 @@ void sci_clear_cmdkey(ScintillaObject *sci, gint key)
 }
 
 
-/** Get text between @a start and @a end.
+/** Gets text between @a start and @a end.
  * @deprecated sci_get_text_range is deprecated and should not be used in newly-written code.
  * Use sci_get_contents_range() instead.
  *
@@ -893,7 +893,7 @@ void sci_get_text_range(ScintillaObject *sci, gint start, gint end, gchar *text)
 }
 
 
-/** Get text between @a start and @a end.
+/** Gets text between @a start and @a end.
  *
  * @param sci Scintilla widget.
  * @param start Start.
@@ -922,7 +922,7 @@ void sci_selection_duplicate(ScintillaObject *sci)
 }
 
 
-/** Insert text.
+/** Inserts text.
  * @param sci Scintilla widget.
  * @param pos Position, or -1 for current.
  * @param text Text. */
@@ -968,7 +968,7 @@ void sci_set_readonly(ScintillaObject *sci, gboolean readonly)
 }
 
 
-/** A simple convenience function for sending Scintilla commands without any parameters.
+/** Sends Scintilla commands without any parameters.
  * @param sci The Scintilla @c GtkWidget.
  * @param cmd @c SCI_COMMAND.
  * @see http://scintilla.org for the documentation.
@@ -981,7 +981,7 @@ void sci_send_command(ScintillaObject *sci, gint cmd)
 }
 
 
-/** Get current line number.
+/** Gets current line number.
  * @param sci Scintilla widget.
  * @return Line number. */
 gint sci_get_current_line(ScintillaObject *sci)
@@ -1070,7 +1070,7 @@ void sci_set_autoc_max_height(ScintillaObject *sci, gint val)
 }
 
 
-/** Find a matching brace at @a pos.
+/** Finds a matching brace at @a pos.
  * @param sci Scintilla widget.
  * @param pos Position.
  * @return Matching brace position.
@@ -1113,7 +1113,7 @@ gint sci_get_pos_at_line_sel_end(ScintillaObject *sci, gint line)
 }
 
 
-/** Get selection mode.
+/** Gets selection mode.
  * @param sci Scintilla widget.
  * @return Selection mode. */
 gint sci_get_selection_mode(ScintillaObject *sci)
@@ -1122,7 +1122,7 @@ gint sci_get_selection_mode(ScintillaObject *sci)
 }
 
 
-/** Set selection mode.
+/** Sets selection mode.
  * @param sci Scintilla widget.
  * @param mode Mode. */
 void sci_set_selection_mode(ScintillaObject *sci, gint mode)
diff --git a/src/ui_utils.c b/src/ui_utils.c
index 543816b0..b5bad76f 100644
--- a/src/ui_utils.c
+++ b/src/ui_utils.c
@@ -135,7 +135,7 @@ static void set_statusbar(const gchar *text, gboolean allow_override)
 }
 
 
-/** Display text on the statusbar.
+/** Displays text on the statusbar.
  * @param log Whether the message should be recorded in the Status window.
  * @param format A @c printf -style string. */
 void ui_set_statusbar(gboolean log, const gchar *format, ...)
@@ -706,7 +706,7 @@ static void on_doc_sensitive_widget_destroy(GtkWidget *widget, G_GNUC_UNUSED gpo
 }
 
 
-/** Add a widget to the list of widgets that should be set sensitive/insensitive
+/** Adds a widget to the list of widgets that should be set sensitive/insensitive
  * when some documents are present/no documents are open.
  * It will be removed when the widget is destroyed.
  * @param widget The widget to add.
@@ -1264,8 +1264,7 @@ GtkWidget *ui_frame_new_with_alignment(const gchar *label_text, GtkWidget **alig
 }
 
 
-/** Convenience function for getting a fixed border for dialogs that doesn't
- * increase the button box border.
+/** Makes a fixed border for dialogs without increasing the button box border.
  * @param dialog The parent container for the @c GtkVBox.
  * @return The packed @c GtkVBox. */
 GtkWidget *ui_dialog_vbox_new(GtkDialog *dialog)
@@ -1297,7 +1296,7 @@ GtkWidget *ui_button_new_with_image(const gchar *stock_id, const gchar *text)
 }
 
 
-/** Create a @c GtkImageMenuItem with a stock image and a custom label.
+/** Creates a @c GtkImageMenuItem with a stock image and a custom label.
  * @param stock_id Stock image ID, e.g. @c GTK_STOCK_OPEN.
  * @param label Menu item label, can include mnemonics.
  * @return The new @c GtkImageMenuItem.
@@ -1327,7 +1326,7 @@ static void entry_clear_icon_release_cb(GtkEntry *entry, gint icon_pos,
 }
 
 
-/** Convenience function to add a small clear icon to the right end of the passed @a entry.
+/** Adds a small clear icon to the right end of the passed @a entry.
  *  A callback to clear the contents of the GtkEntry is automatically added.
  *
  *  This feature is only available with GTK 2.16 but implemented as a runtime check,
@@ -1696,7 +1695,7 @@ void ui_statusbar_showhide(gboolean state)
 }
 
 
-/** Pack all @c GtkWidgets passed after the row argument into a table, using
+/** Packs all @c GtkWidgets passed after the row argument into a table, using
  * one widget per cell. The first widget is not expanded as the table grows,
  * as this is usually a label.
  * @param table
@@ -2037,7 +2036,7 @@ void ui_widget_set_tooltip_text(GtkWidget *widget, const gchar *text)
 }
 
 
-/** This function returns a widget from a name in a component, usually created by Glade.
+/** Returns a widget from a name in a component, usually created by Glade.
  * Call it with the toplevel widget in the component (i.e. a window/dialog),
  * or alternatively any widget in the component, and the name of the widget
  * you want returned.
@@ -2199,7 +2198,7 @@ GtkWidget *ui_label_set_markup(GtkLabel *label, const gchar *format, ...)
 }
 
 
-/** Add a list of document items to @a menu.
+/** Adds a list of document items to @a menu.
  * @param menu Menu.
  * @param active Which document to highlight, or @c NULL.
  * @param callback is used for each menu item's @c "activate" signal and will be passed
@@ -2240,7 +2239,7 @@ void ui_menu_add_document_items(GtkMenu *menu, GeanyDocument *active, GCallback
 }
 
 
-/** Check whether the passed @a keyval is the Enter or Return key.
+/** Checks whether the passed @a keyval is the Enter or Return key.
  * There are three different Enter/Return key values
  * (@c GDK_Return, @c GDK_ISO_Enter, @c GDK_KP_Enter).
  * This is just a convenience function.
diff --git a/src/ui_utils.h b/src/ui_utils.h
index 48938f16..9da878b5 100644
--- a/src/ui_utils.h
+++ b/src/ui_utils.h
@@ -24,7 +24,7 @@
 #ifndef GEANY_UI_UTILS_H
 #define GEANY_UI_UTILS_H 1
 
-/** Set a name to lookup @a widget from @a owner.
+/** Sets a name to lookup @a widget from @a owner.
  * @param owner Usually a @c GtkWindow.
  * @param widget Widget.
  * @param widget_name Name.
diff --git a/src/utils.c b/src/utils.c
index 147dd1b6..4e11b23f 100644
--- a/src/utils.c
+++ b/src/utils.c
@@ -660,7 +660,7 @@ gint utils_strpos(const gchar *haystack, const gchar *needle)
 
 
 /**
- *  This is a convenience function to retrieve a formatted date/time string from strftime().
+ *  Retrieves a formatted date/time string from strftime().
  *  This function should be preferred to directly calling strftime() since this function
  *  works on UTF-8 encoded strings.
  *
@@ -729,7 +729,7 @@ gchar *utils_get_initials(const gchar *name)
 
 
 /**
- *  Convenience function for g_key_file_get_integer() to add a default value argument.
+ *  Wraps g_key_file_get_integer() to add a default value argument.
  *
  *  @param config A GKeyFile object.
  *  @param section The group name to look in for the key.
@@ -760,7 +760,7 @@ gint utils_get_setting_integer(GKeyFile *config, const gchar *section, const gch
 
 
 /**
- *  Convenience function for g_key_file_get_boolean() to add a default value argument.
+ *  Wraps g_key_file_get_boolean() to add a default value argument.
  *
  *  @param config A GKeyFile object.
  *  @param section The group name to look in for the key.
@@ -791,7 +791,7 @@ gboolean utils_get_setting_boolean(GKeyFile *config, const gchar *section, const
 
 
 /**
- *  Convenience function for g_key_file_get_string() to add a default value argument.
+ *  Wraps g_key_file_get_string() to add a default value argument.
  *
  *  @param config A GKeyFile object.
  *  @param section The group name to look in for the key.
@@ -1488,7 +1488,7 @@ static guint utils_string_replace_helper(GString *haystack, const gchar *needle,
  * @param needle The string which should be replaced.
  * @param replace The replacement for @a needle.
  *
- * @return amount of replacements done
+ * @return Number of replacements made.
  **/
 guint utils_string_replace_all(GString *haystack, const gchar *needle, const gchar *replace)
 {
@@ -1497,7 +1497,7 @@ guint utils_string_replace_all(GString *haystack, const gchar *needle, const gch
 
 
 /**
- * Convenience function to replace only the first occurrence of @a needle in @a haystack
+ * Replaces only the first occurrence of @a needle in @a haystack
  * with @a replace.
  * For details, see utils_string_replace_all().
  *
@@ -1505,7 +1505,7 @@ guint utils_string_replace_all(GString *haystack, const gchar *needle, const gch
  * @param needle The string which should be replaced.
  * @param replace The replacement for @a needle.
  *
- * @return amount of replacements done
+ * @return Number of replacements made.
  *
  *  @since 0.16
  */
diff --git a/src/utils.h b/src/utils.h
index 266be957..78926b8c 100644
--- a/src/utils.h
+++ b/src/utils.h
@@ -33,7 +33,7 @@
 #include <time.h>
 
 
-/** Returns: TRUE if @a ptr points to a non-zero value. */
+/** Returns TRUE if @a ptr points to a non-zero value. */
 #define NZV(ptr) \
 	(G_LIKELY((ptr)) && G_LIKELY((ptr)[0]))
 
@@ -49,8 +49,8 @@
 		g_free(setptr_tmp);\
 	}
 
-/** Like glibc's @c strdupa(), but portable.
- * Duplicate a string on the stack using @c g_alloca().
+/** Duplicates a string on the stack using @c g_alloca().
+ * Like glibc's @c strdupa(), but portable.
  * @note You must include @c string.h yourself.
  * @warning Don't use excessively or for long strings otherwise there may be stack exhaustion -
  *          see the GLib docs for @c g_alloca(). */