* cosmetics

lib/mu-bookmarks.h

@@ -23,16 +23,25 @@
 #include <glib.h>
 
 G_BEGIN_DECLS
+/**
+ * @addtogroup MuBookmarks
+ * Functions for dealing with bookmarks
+ * @{
+ */
 
+struct _MuBookmarks;
+/*! \struct MuBookmarks
+ * \brief Opaque structure representing a sequence of bookmarks
+ */
 typedef struct _MuBookmarks MuBookmarks;
 
 
 /**
  * create a new bookmarks object. when it's no longer needed, use
  * mu_bookmarks_destroy
- * 
+ *
  * @param bmpath path to the bookmarks file
- * 
+ *
  * @return a new BookMarks object, or NULL in case of error
  */
 MuBookmarks *mu_bookmarks_new (const gchar *bmpath)
@@ -40,7 +49,7 @@ MuBookmarks *mu_bookmarks_new (const gchar *bmpath)
 
 /**
  * destroy a bookmarks object
- * 
+ *
  * @param bm a bookmarks object, or NULL
  */
 void         mu_bookmarks_destroy (MuBookmarks *bm);
@@ -48,10 +57,10 @@ void         mu_bookmarks_destroy (MuBookmarks *bm);
 
 /**
  * get the value for some bookmark
- * 
+ *
  * @param bm a valid bookmarks object
  * @param name name of the bookmark to retrieve
- * 
+ *
  * @return the value of the bookmark or NULL in case in error, e.g. if
  * the bookmark was not found
  */
@@ -62,7 +71,7 @@ typedef void (*MuBookmarksForeachFunc) (const gchar *key, const gchar *val,
 
 /**
  * call a function for each bookmark
- * 
+ *
  * @param bm a valid bookmarks object
  * @param func a callback function to be called for each bookmarks
  * @param user_data a user pointer passed to the callback
@@ -70,6 +79,8 @@ typedef void (*MuBookmarksForeachFunc) (const gchar *key, const gchar *val,
 void         mu_bookmarks_foreach (MuBookmarks *bm, MuBookmarksForeachFunc func,
 				   gpointer user_data);
 
+/** @} */
+
 G_END_DECLS
 
 #endif /*__MU_BOOKMARKS_H__*/

lib/mu-date.h

@@ -24,17 +24,22 @@
 
 G_BEGIN_DECLS
 
+/**
+ * @addtogroup MuDate
+ * Date-related functions
+ * @{
+ */
 
 /**
  * get a string for a given time_t
- * 
+ *
  * mu_date_str_s returns a ptr to a static buffer,
  * while mu_date_str returns dynamically allocated
  * memory that must be freed after use.
  *
- * @param frm the format of the string (in strftime(3) format) 
+ * @param frm the format of the string (in strftime(3) format)
  * @param t the time as time_t
- * 
+ *
  * @return a string representation of the time; see above for what to
  * do with it. Lenght is max. 128 bytes, inc. the ending \0.  if the
  * format is too long, the value will be truncated. in practice this
@@ -49,28 +54,28 @@ char*       mu_date_str   (const char* frm, time_t t) G_GNUC_WARN_UNUSED_RESULT;
  * get a display string for a given time_t; if the given is less than
  * 24h from the current time, we display the time, otherwise the date,
  * using the preferred date/time for the current locale
- * 
+ *
  * mu_str_display_date_s returns a ptr to a static buffer,
  *
  * @param t the time as time_t
- * 
+ *
  * @return a string representation of the time/date
  */
 const char* mu_date_display_s (time_t t);
 
 /**
- * 
+ *
  * parse strings like 1h, 3w, 2m to mean '1 hour before now', '3 weeks
  * before now' and '2 * 30 days before now'
- * 
+ *
  * the format is <n>(h|d|w|m|y), where <n> is an integer > 0, and
  * h=hour, d=day, w=week, m=30 days, year=365 days. function returns
  * *now* minus this value as time_t (UTC)
  *
  * if the number cannot be parsed, return (time_t)-1
- * 
+ *
  * @param str a str
- * 
+ *
  * @return the time_t of the point in time indicated by 'now' minus
  * the value, or (time_t)-1 otherwise
  */
@@ -85,12 +90,12 @@ time_t mu_date_parse_hdwmy (const char* str);
  * if is_begin is TRUE, add to the 'floor' (e.g,
  * 20110101=>20110101000000), otherwise go to the 'ceiling',
  * e.g. 2009=>20091231235050)
- * 
+ *
  * @param date a date string (assumed to have the beginning of the
  * date, this is not checked
  * @param is_begin if TRUE go to floor (as described), otherwise to
  * the ceiling
- * 
+ *
  * @return mu_date_complete: return a newly allocated string (free
  * with g_free) with the full, 14-char date; mu_date_complete_s:
  * return a statically allocated string. NOT REENTRANT.
@@ -101,12 +106,12 @@ const char* mu_date_complete_s (const char *date, gboolean is_begin);
 
 
 /**
- * 
- * 
- * @param datespec 
- * @param is_begin 
- * 
- * @return 
+ *
+ *
+ * @param datespec
+ * @param is_begin
+ *
+ * @return
  */
 const char* mu_date_interpret_s (const char *datespec, gboolean is_begin);
 char* mu_date_interpret (const char *datespec, gboolean is_begin);
@@ -115,10 +120,10 @@ char* mu_date_interpret (const char *datespec, gboolean is_begin);
 
 /**
  * convert a date of the form 'YYYYMMDDHHMMSS' into time_t
- * 
+ *
  * @param date a date str of the form 'YYYYMMDDHHMMSS'
  * @param local if TRUE, source is assumed to bin in local time, UTC otherwise
- * 
+ *
  * @return the corresponding time_t, or (time_t)-1 in case of error
  */
 time_t mu_date_str_to_time_t (const char* date, gboolean local);
@@ -129,10 +134,10 @@ time_t mu_date_str_to_time_t (const char* date, gboolean local);
 /**
  * convert a time_t value into a date string of the form
  * 'YYYYMMDDHHMMSS'; assume UTC
- * 
+ *
  * @param t a time_t value
- * @param local if TRUE, convert to local time, otherwise use UTC 
- * 
+ * @param local if TRUE, convert to local time, otherwise use UTC
+ *
  * @return mu_date_time_t_to_str_s: a static string (don't modify,
  * non-reentrant) of the form 'YYYYMMDDHHMMSS'; mu_date_time_t_to_str:
  * return a newly allocated string with the same.
@@ -140,7 +145,7 @@ time_t mu_date_str_to_time_t (const char* date, gboolean local);
 const char* mu_date_time_t_to_str_s (time_t t, gboolean local);
 char* mu_date_time_t_to_str (time_t t, gboolean local);
 
-
+/** @} */
 
 G_END_DECLS
 

lib/mu-str.h

@@ -32,6 +32,7 @@ G_BEGIN_DECLS
 
 /**
  * @addtogroup MuStr
+ * Various string utilities
  * @{
  */
 
@@ -48,7 +49,8 @@ G_BEGIN_DECLS
  *   returns a newly allocated string that you must free with g_free
  *   when done with it.
  *
- * @param str a 'contact str' (ie., what is in the To/Cc/Bcc/From fields), or NULL
+ * @param str a 'contact str' (ie., what is in the To/Cc/Bcc/From
+ * fields), or NULL
  *
  * @return a newly allocated string with a display contact
  */