Developer documentation improvements.

7 files changed, 98 insertions, 36 deletions

diff --git a/e-util/e-account-utils.c b/e-util/e-account-utils.c
index 5fdffd8be2..4d169d956a 100644
--- a/e-util/e-account-utils.c
+++ b/e-util/e-account-utils.c
@@ -21,6 +21,13 @@
 
 static EAccountList *global_account_list;
 
+/**
+ * e_get_account_list:
+ *
+ * Returns the global #EAccountList.
+ *
+ * Returns: the global #EAccountList
+ **/
 EAccountList *
 e_get_account_list (void)
 {
@@ -37,6 +44,13 @@ e_get_account_list (void)
 	return global_account_list;
 }
 
+/**
+ * e_get_default_account:
+ *
+ * Returns the #EAccount marked as the default mail account.
+ *
+ * Returns: the default #EAccount
+ **/
 EAccount *
 e_get_default_account (void)
 {
@@ -50,6 +64,12 @@ e_get_default_account (void)
 	return (EAccount *) account;
 }
 
+/**
+ * e_set_default_account:
+ * @account: an #EAccount
+ *
+ * Marks @account as the default mail account.
+ **/
 void
 e_set_default_account (EAccount *account)
 {
@@ -61,6 +81,15 @@ e_set_default_account (EAccount *account)
 	e_account_list_set_default (account_list, account);
 }
 
+/**
+ * e_get_account_by_name:
+ * @name: a mail account name
+ *
+ * Returns the #EAccount with the given name, or %NULL if no such
+ * account exists.
+ *
+ * Returns: an #EAccount having the given account name, or %NULL
+ **/
 EAccount *
 e_get_account_by_name (const gchar *name)
 {
@@ -78,6 +107,15 @@ e_get_account_by_name (const gchar *name)
 	return (EAccount *) account;
 }
 
+/**
+ * e_get_account_by_uid:
+ * @uid: a mail account UID
+ *
+ * Returns the #EAccount with the given unique ID, or %NULL if no such
+ * account exists.
+ *
+ * Returns: an #EAccount having the given unique ID, or %NULL
+ **/
 EAccount *
 e_get_account_by_uid (const gchar *uid)
 {
diff --git a/e-util/e-account-utils.h b/e-util/e-account-utils.h
index f2ae8fc5dc..ca184404ef 100644
--- a/e-util/e-account-utils.h
+++ b/e-util/e-account-utils.h
@@ -15,6 +15,11 @@
  * Copyright (C) 1999-2008 Novell, Inc. (www.novell.com)
  */
 
+/**
+ * SECTION: e-account-utils
+ * @include: e-util/e-account-utils.h
+ **/
+
 #ifndef E_ACCOUNT_UTILS_H
 #define E_ACCOUNT_UTILS_H
 
diff --git a/e-util/e-charset.c b/e-util/e-charset.c
index 329f513ec7..ffee5a8f4a 100644
--- a/e-util/e-charset.c
+++ b/e-util/e-charset.c
@@ -123,6 +123,8 @@ static ECharset charsets[] = {
  * US-ASCII).  Any other character sets of the same language class as
  * the default will be added next, followed by the remaining character
  * sets.
+ *
+ * Returns: the radio action group
  **/
 GSList *
 e_charset_add_radio_actions (GtkActionGroup *action_group,
diff --git a/e-util/e-html-utils.c b/e-util/e-html-utils.c
index b80ee17891..03e5b73fc0 100644
--- a/e-util/e-html-utils.c
+++ b/e-util/e-html-utils.c
@@ -178,14 +178,15 @@ is_citation (const guchar *c, gboolean saw_citation)
  *
  * The set of possible flags is:
  *
- *   - E_TEXT_TO_HTML_PRE: wrap the output HTML in <PRE> and </PRE>.
- *     Should only be used if @input is the entire buffer to be
- *     converted. If e_text_to_html is being called with small pieces
- *     of data, you should wrap the entire result in <PRE> yourself.
+ *   - E_TEXT_TO_HTML_PRE: wrap the output HTML in &lt;PRE&gt; and
+ *     &lt;/PRE&gt;  Should only be used if @input is the entire
+ *     buffer to be converted. If e_text_to_html is being called with
+ *     small pieces of data, you should wrap the entire result in
+ *     &lt;PRE&gt; yourself.
  *
- *   - E_TEXT_TO_HTML_CONVERT_NL: convert "\n" to "<BR>\n" on output.
- *     (should not be used with E_TEXT_TO_HTML_PRE, since that would
- *     result in double-newlines).
+ *   - E_TEXT_TO_HTML_CONVERT_NL: convert "\n" to "&lt;BR&gt;n" on
+ *     output.  (Should not be used with E_TEXT_TO_HTML_PRE, since
+ *     that would result in double-newlines.)
  *
  *   - E_TEXT_TO_HTML_CONVERT_SPACES: convert a block of N spaces
  *     into N-1 non-breaking spaces and one normal space. A space
@@ -197,14 +198,14 @@ is_citation (const guchar *c, gboolean saw_citation)
  *     If E_TEXT_TO_HTML_CONVERT_NL and E_TEXT_TO_HTML_CONVERT_SPACES
  *     are both defined, then TABs will also be converted to spaces.
  *
- *   - E_TEXT_TO_HTML_CONVERT_URLS: wrap <a href="..."> </a> around
- *     strings that look like URLs.
+ *   - E_TEXT_TO_HTML_CONVERT_URLS: wrap &lt;a href="..."&gt; &lt;/a&gt;
+ *     around strings that look like URLs.
  *
- *   - E_TEXT_TO_HTML_CONVERT_ADDRESSES: wrap <a href="mailto:..."> </a> around
- *     strings that look like mail addresses.
+ *   - E_TEXT_TO_HTML_CONVERT_ADDRESSES: wrap &lt;a href="mailto:..."&gt;
+ *     &lt;/a&gt; around strings that look like mail addresses.
  *
- *   - E_TEXT_TO_HTML_MARK_CITATION: wrap <font color="..."> </font> around
- *     citations (lines beginning with "> ", etc).
+ *   - E_TEXT_TO_HTML_MARK_CITATION: wrap &lt;font color="..."&gt;
+ *     &lt;/font&gt; around citations (lines beginning with "> ", etc).
  *
  *   - E_TEXT_TO_HTML_ESCAPE_8BIT: flatten everything to US-ASCII
  *
diff --git a/e-util/e-module.h b/e-util/e-module.h
index a8120563d3..6f99fc0515 100644
--- a/e-util/e-module.h
+++ b/e-util/e-module.h
@@ -21,7 +21,6 @@
 
 /**
  * SECTION: e-module
- * @short_description: generic module loader
  * @include: e-util/e-module.h
  **/
 
diff --git a/e-util/e-util.c b/e-util/e-util.c
index 4e954a1c6c..f4bf144c5d 100644
--- a/e-util/e-util.c
+++ b/e-util/e-util.c
@@ -523,22 +523,25 @@ e_type_traverse (GType parent_type,
 
 /**
  * e_str_without_underscores:
- * @s: the string to strip underscores from.
+ * @string: the string to strip underscores from
  *
- * Strips underscores from a string in the same way @gtk_label_new_with_mnemonis does.
- * The returned string should be freed.
+ * Strips underscores from a string in the same way
+ * @gtk_label_new_with_mnemonics does.  The returned string should be freed
+ * using g_free().
+ *
+ * Returns: a newly-allocated string without underscores
  */
 gchar *
-e_str_without_underscores (const gchar *s)
+e_str_without_underscores (const gchar *string)
 {
 	gchar *new_string;
 	const gchar *sp;
 	gchar *dp;
 
-	new_string = g_malloc (strlen (s) + 1);
+	new_string = g_malloc (strlen (string) + 1);
 
 	dp = new_string;
-	for (sp = s; *sp != '\0'; sp ++) {
+	for (sp = string; *sp != '\0'; sp ++) {
 		if (*sp != '_') {
 			*dp = *sp;
 			dp ++;
@@ -614,7 +617,8 @@ e_int_compare (gconstpointer x, gconstpointer y)
 }
 
 gboolean
-e_write_file_uri (const gchar *filename, const gchar *data)
+e_write_file_uri (const gchar *filename,
+                  const gchar *data)
 {
 	gboolean res;
 	gsize length;
@@ -1051,7 +1055,7 @@ e_get_weekday_name (GDateWeekday weekday,
  * To convert from a double to a string in a locale-insensitive way, use
  * @g_ascii_dtostr.
  *
- * Return value: the gdouble value.
+ * Returns: the gdouble value
  **/
 gdouble
 e_flexible_strtod (const gchar *nptr, gchar **endptr)
@@ -1188,7 +1192,7 @@ e_flexible_strtod (const gchar *nptr, gchar **endptr)
  * of the resulting string will never be larger than
  * @G_ASCII_DTOSTR_BUF_SIZE bytes.
  *
- * Return value: The pointer to the buffer with the converted string.
+ * Returns: the pointer to the buffer with the converted string
  **/
 gchar *
 e_ascii_dtostr (gchar *buffer, gint buf_len, const gchar *format, gdouble d)
@@ -1448,11 +1452,14 @@ e_file_lock_exists ()
 
 /**
  * e_util_guess_mime_type:
- * @filename: it's a local file name, or URI.
- * @localfile: set to TRUE if can check the local file content, FALSE to check only based on the filename itself.
- * Returns: NULL or newly allocated string with a mime_type of the given file. Free with g_free.
+ * @filename: a local file name, or URI
+ * @localfile: %TRUE to check the file content, FALSE to check only the name
+ *
+ * Tries to determine the MIME type for @filename.  Free the returned
+ * string with g_free().
  *
- * Guesses mime_type for the given filename.
+ * Returns: the MIME type of @filename, or %NULL if the the MIME type could
+ *          not be determined
  **/
 gchar *
 e_util_guess_mime_type (const gchar *filename, gboolean localfile)
@@ -1501,9 +1508,11 @@ e_util_guess_mime_type (const gchar *filename, gboolean localfile)
 /**
  * e_util_filename_to_uri:
  * @filename: local file name.
- * Returns: either newly allocated string or NULL. Free with g_free.
  *
- * Converts local file name to URI.
+ * Converts a local file name to a URI.  Free the returned string with
+ * g_free().
+ *
+ * Returns: a newly allocated string or %NULL
  **/
 gchar *
 e_util_filename_to_uri (const gchar *filename)
@@ -1525,10 +1534,12 @@ e_util_filename_to_uri (const gchar *filename)
 
 /**
  * e_util_uri_to_filename:
- * @uri: uri.
- * Returns: either newly allocated string or NULL. Free with g_free.
+ * @uri: a URI
+ *
+ * Converts a URI to a local file name.  %NULL indicates no such
+ * local file name exists.  Free the returned string with g_free().
  *
- * Converts URI to local file name. NULL indicates no such local file name exists.
+ * Returns: either newly allocated string or %NULL
  **/
 gchar *
 e_util_uri_to_filename (const gchar *uri)
@@ -1555,10 +1566,11 @@ e_util_uri_to_filename (const gchar *uri)
  * @buffer: Read content or the file. Should not be NULL. Returned value should be freed with g_free.
  * @read: Number of actually read bytes. Should not be NULL.
  * @error: Here will be returned an error from reading operations. Can be NULL. Not every time is set when returned FALSE.
- * Returns: Whether was reading successful or not.
  *
  * Reads synchronously content of the file, to which is pointed either by path or by URI.
  * Mount point should be already mounted when calling this function.
+ *
+ * Returns: Whether was reading successful or not.
  **/
 gboolean
 e_util_read_file (const gchar *filename, gboolean filename_is_uri, gchar **buffer, gsize *read, GError **error)
diff --git a/e-util/e-util.h b/e-util/e-util.h
index 68abcd4cba..16b3373279 100644
--- a/e-util/e-util.h
+++ b/e-util/e-util.h
@@ -20,8 +20,13 @@
  *
  */
 
-#ifndef _E_UTIL_H_
-#define _E_UTIL_H_
+/**
+ * SECTION: e-util
+ * @include: e-util/e-util.h
+ **/
+
+#ifndef E_UTIL_H
+#define E_UTIL_H
 
 #include <sys/types.h>
 #include <gtk/gtk.h>
@@ -154,4 +159,4 @@ GType		e_camel_object_get_type		(void);
 
 G_END_DECLS
 
-#endif /* _E_UTIL_H_ */
+#endif /* E_UTIL_H */