* mu-msg-fields: document public functions

src/mu-msg-fields.c

@@ -21,9 +21,9 @@
 #include "mu-msg-fields.h"
 
 enum _FieldFlags { 
-	FLAG_XAPIAN         = 1 << 1, /* field stored as a string the in xapian db*/
-	FLAG_GMIME          = 1 << 2, /* field retrieved by reading msg with gmime */
-	FLAG_XAPIAN_INDEX   = 1 << 3  /* field is indexed in xapian */
+	FLAG_XAPIAN        = 1 << 1, /* field stored as a string  in xapian db */
+	FLAG_GMIME         = 1 << 2, /* field retrieved by through gmime */
+	FLAG_XAPIAN_INDEX  = 1 << 3  /* field is indexed in xapian */
 };
 typedef enum _FieldFlags FieldFlags;
 

src/mu-msg-fields.h

@@ -61,28 +61,142 @@ enum _MuMsgFieldType {
 typedef enum _MuMsgFieldType MuMsgFieldType;
 static const guint MU_MSG_FIELD_TYPE_NONE = MU_MSG_FIELD_TYPE_NUM + 1;
 
-
 typedef void (*MuMsgFieldForEachFunc) (const MuMsgField *field, 
 				       gconstpointer data);
+
+/** 
+ * iterator over all possible message fields
+ * 
+ * @param func a function called for each field
+ * @param data a user data pointer passed the callback function
+ */
 void mu_msg_field_foreach (MuMsgFieldForEachFunc func, gconstpointer data);
 
 
+/** 
+ * get the name of the field -- this a name that can be use in queries,
+ * ie. 'subject:foo', with 'subject' being the name
+ * 
+ * @param field a MuMsgField
+ * 
+ * @return the name of the field as a constant string, or
+ * NULL if the field is unknown
+ */
 const char*  mu_msg_field_name (const MuMsgField *field)         G_GNUC_CONST;
+
+/** 
+ * get the shortcut of the field -- this a shortcut that can be use in
+ * queries, ie. 's:foo', with 's' meaning 'subject' being the name
+ * 
+ * @param field a MuMsgField
+ * 
+ * @return the shortcut of the field as a constant string, or
+ * NULL if the field is unknown
+ */
 const char*  mu_msg_field_shortcut (const MuMsgField *field)     G_GNUC_CONST;
+
+/** 
+ * get the xapian prefix of the field -- that is, the prefix used in
+ * the Xapian database to identify the field
+ * 
+ * @param field a MuMsgField
+ * 
+ * @return the xapian prefix of the field as a constant string, or
+ * NULL if the field is unknown
+ */
 const char*  mu_msg_field_xapian_prefix (const MuMsgField *field) G_GNUC_PURE;
 
+/** 
+ * get the numerical ID of the field
+ * 
+ * @param field a MuMsgField
+ * 
+ * @return an id, or MU_MSG_FIELD_TYPE_NONE if the field is not known
+ */
 MuMsgFieldId mu_msg_field_id (const MuMsgField *field)           G_GNUC_CONST;
+
+
+/** 
+ * get the type of the field (string, size, time etc.)
+ * 
+ * @param field a MuMsgField
+ * 
+ * @return the type of the field (a #MuMsgFieldType), or
+ * MU_MSG_FIELD_TYPE_NONE if it is not found
+ */
 MuMsgFieldType mu_msg_field_type (const MuMsgField *field)         G_GNUC_CONST;
 
-gboolean mu_msg_field_is_numeric (const MuMsgField *field)         G_GNUC_CONST;
 
+/** 
+ * is the field numeric (has type MU_MSG_FIELD_TYPE_(BYTESIZE|TIME_T|INT))?
+ * 
+ * @param field a MuMsgField
+ * 
+ * @return TRUE if the field is numeric, FALSE otherwise
+ */
+gboolean mu_msg_field_is_numeric          (const MuMsgField *field) G_GNUC_CONST;
+
+/** 
+ * is the field Xapian-enabled? That is, should this field be stored
+ * (as a string) in the Xapian database?
+ * 
+ * @param field a MuMsgField
+ * 
+ * @return TRUE if the field is Xapian-enabled, FALSE otherwise
+ */
 gboolean mu_msg_field_is_xapian_enabled   (const MuMsgField *field) G_GNUC_PURE;
-gboolean mu_msg_field_is_gmime_enabled    (const MuMsgField *field) G_GNUC_PURE;
+
+
+/** 
+ * is the field Xapian-indexable? That is, should this field be
+ * indexed in the in the Xapian database, so we can use the all the
+ * phrasing, stemming etc. magic
+ * 
+ * @param field a MuMsgField
+ * 
+ * @return TRUE if the field is Xapian-enabled, FALSE otherwise
+ */
 gboolean mu_msg_field_is_xapian_indexable (const MuMsgField *field) G_GNUC_PURE;
 
+
+/** 
+ * is the field gmime-enabled? That is, can be field be retrieved
+ * using GMime?
+ * 
+ * @param field a MuMsgField
+ * 
+ * @return TRUE if the field is Gmime-enabled, FALSE otherwise
+ */
+gboolean mu_msg_field_is_gmime_enabled    (const MuMsgField *field) G_GNUC_PURE;
+
+
+/** 
+ * get the corresponding MuMsgField for a name (as in mu_msg_field_name)
+ * 
+ * @param str a name
+ * 
+ * @return a MuMsgField, or NULL if it could not be found
+ */
 const MuMsgField*  mu_msg_field_from_name     (const char* str)  G_GNUC_PURE;
+
+
+/** 
+ * get the corresponding MuMsgField for a shortcut (as in mu_msg_field_shortcut)
+ * 
+ * @param kar a shortcut character
+ * 
+ * @return a MuMsgField, or NULL if it could not be found
+ */
 const MuMsgField*  mu_msg_field_from_shortcut (char kar)         G_GNUC_CONST;
-const MuMsgField*  mu_msg_field_from_id       (MuMsgFieldId)     G_GNUC_CONST;
+
+/** 
+ * get the corresponding MuMsgField for an id (as in mu_msg_field_id)
+ * 
+ * @param id an id
+ * 
+ * @return a MuMsgField, or NULL if it could not be found
+ */
+const MuMsgField*  mu_msg_field_from_id       (MuMsgFieldId id)  G_GNUC_CONST;
 
 G_END_DECLS