diff --git a/lib/mu-bookmarks.h b/lib/mu-bookmarks.h index a23999ce..036131be 100644 --- a/lib/mu-bookmarks.h +++ b/lib/mu-bookmarks.h @@ -23,16 +23,25 @@ #include 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__*/ diff --git a/lib/mu-date.h b/lib/mu-date.h index bb9f5b06..505d7ca5 100644 --- a/lib/mu-date.h +++ b/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 (h|d|w|m|y), where 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 diff --git a/lib/mu-str.h b/lib/mu-str.h index dc5318c7..a9106a6e 100644 --- a/lib/mu-str.h +++ b/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 */