From f9f3c11f28dc5d09b78b5022c0e656f966a4cbe1 Mon Sep 17 00:00:00 2001
From: "Dirk-Jan C. Binnema" <djcb@djcbsoftware.nl>
Date: Sun, 15 May 2011 10:40:58 +0300
Subject: [PATCH] * mu_msg_file.h, mu_msg.h: documentation improvements

---
 src/mu-msg-file.h | 14 ++++++++------
 src/mu-msg.h      |  2 +-
 2 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/src/mu-msg-file.h b/src/mu-msg-file.h
index a28e3a08..570a2d89 100644
--- a/src/mu-msg-file.h
+++ b/src/mu-msg-file.h
@@ -23,7 +23,7 @@
 struct _MuMsgFile;
 typedef struct _MuMsgFile MuMsgFile;
 
-/** 
+/**
  * create a new message from a file
  * 
  * @param path full path to the message
@@ -35,7 +35,7 @@ typedef struct _MuMsgFile MuMsgFile;
 MuMsgFile *mu_msg_file_new (const char *path,
 			    const char* mdir, GError **err);
 
-/** 
+/**
  * destroy a MuMsgFile object
  *
  * @param self object to destroy, or NULL
@@ -43,14 +43,16 @@ MuMsgFile *mu_msg_file_new (const char *path,
 void mu_msg_file_destroy (MuMsgFile *self);
 
 
-/** 
+/**
  * get a string value for this message
  * 
  * @param self a valid MuMsgFile
  * @param msfid the message field id to get (must be string-based one) *
  * @param do_free receives TRUE or FALSE, conveying if this string
- * should be freed (TRUE) or not by caller. In case 'FALSE', this
- * function should be treated as if it were return a const char*
+ * should be owned & freed (TRUE) or not by caller. In case 'FALSE',
+ * this function should be treated as if it were returning a const
+ * char*, and note that in that case the string is only valid as long
+ * as the MuMsgFile is alive, ie. before mu_msg_file_destroy
  * 
  * @return a const string, or NULL
  */
@@ -58,7 +60,7 @@ char* mu_msg_file_get_str_field (MuMsgFile *self,
 				 MuMsgFieldId msfid,
 				 gboolean *do_free);
 
-/** 
+/**
  * get a numeric value for this message -- the return value should be
  * cast into the actual type, e.g., time_t, MuMsgPrio etc.
  * 
diff --git a/src/mu-msg.h b/src/mu-msg.h
index 494b027a..77b194a3 100644
--- a/src/mu-msg.h
+++ b/src/mu-msg.h
@@ -32,7 +32,7 @@ typedef struct _MuMsg MuMsg;
 
 /**
  * create a new MuMsg* instance which parses a message and provides
- * read access to its properties; call mu_msg_destroy when done with it.
+ * read access to its properties; call mu_msg_unref when done with it.
  *
  * @param path full path to an email message file
  * @param mdir the maildir for this message; ie, if the path is