* mu_msg_file.h, mu_msg.h: documentation improvements

src/mu-msg-file.h

@@ -49,8 +49,10 @@ void mu_msg_file_destroy (MuMsgFile *self);
  * @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
  */

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