From 5b771a75004ddbd6bfa29b50cdb7a0e188eafbb9 Mon Sep 17 00:00:00 2001 From: Matthew Barnes Date: Tue, 22 Sep 2009 21:06:45 -0400 Subject: Developer documentation improvements. --- e-util/e-account-utils.c | 38 ++++++++++++++++++++++++++++++++++++ e-util/e-account-utils.h | 5 +++++ e-util/e-charset.c | 2 ++ e-util/e-html-utils.c | 27 +++++++++++++------------- e-util/e-module.h | 1 - e-util/e-util.c | 50 ++++++++++++++++++++++++++++++------------------ e-util/e-util.h | 11 ++++++++--- 7 files changed, 98 insertions(+), 36 deletions(-) (limited to 'e-util') 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 
 and
. - * 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 
 yourself.
+ *   - 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_CONVERT_NL: convert "\n" to "
\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 "<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_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   around
- *     strings that look like URLs.
+ *   - E_TEXT_TO_HTML_CONVERT_URLS: wrap <a href="..."> </a>
+ *     around strings that look like URLs.
  *
- *   - E_TEXT_TO_HTML_CONVERT_ADDRESSES: wrap   around
- *     strings that look like mail addresses.
+ *   - E_TEXT_TO_HTML_CONVERT_ADDRESSES: wrap <a href="mailto:...">
+ *     </a> around strings that look like mail addresses.
  *
- *   - E_TEXT_TO_HTML_MARK_CITATION: wrap   around
- *     citations (lines beginning with "> ", etc).
+ *   - E_TEXT_TO_HTML_MARK_CITATION: wrap <font color="...">
+ *     </font> 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 
 #include 
@@ -154,4 +159,4 @@ GType		e_camel_object_get_type		(void);
 
 G_END_DECLS
 
-#endif /* _E_UTIL_H_ */
+#endif /* E_UTIL_H */
-- 
cgit v1.2.3