[geary/wip/713846-plain-inline: 2/3] Slight modifications

[Jim Nelson <jnelson src gnome org>]

commit f6829972c4ef6925632908a32b4528f1ccf9abad
Author: Jim Nelson <jim yorba org>
Date:   Mon Jan 6 16:40:40 2014 -0800

    Slight modifications
    
    Added documentation for the methods in question to explain function
    and parameters' purpose.
    
    Also, don't call InlinePartReplacer if it's known that its output
    isn't desired by the caller.

 src/engine/rfc822/rfc822-message.vala |   47 +++++++++++++++++++++++++++++---
 1 files changed, 42 insertions(+), 5 deletions(-)
---
diff --git a/src/engine/rfc822/rfc822-message.vala b/src/engine/rfc822/rfc822-message.vala
index 5542008..7161bef 100644
--- a/src/engine/rfc822/rfc822-message.vala
+++ b/src/engine/rfc822/rfc822-message.vala
@@ -500,7 +500,10 @@ public class Geary.RFC822.Message : BaseObject {
         if (disposition == null || disposition.disposition_type == Mime.DispositionType.UNSPECIFIED)
             return false;
         
-        if (replacer == null)
+        // if replacer's unavailable, done; if it is available but its output is not desirable
+        // (i.e. the caller doesn't want replaced text, it wants inline text of a format), done
+        // as well
+        if (replacer == null || !allow_only_replaced)
             return false;
         
         // Hand off to the replacer for processing
@@ -509,28 +512,62 @@ public class Geary.RFC822.Message : BaseObject {
         if (replaced_part != null)
             body = replaced_part;
         
-        return allow_only_replaced && (replaced_part != null);
+        return replaced_part != null;
     }
     
+    /**
+     * Returns the HTML portion of the message body, if present.
+     *
+     * The allow_only_replaced flag indicates if it's allowable for the method to return only the
+     * InlinePartReplacer's returned text.  In other words, if only inline MIME section is found
+     * but no HTML portion, allow_only_replaced indicates if the InlinePartReplacer's returned
+     * text constitutes a "body".
+     *
+     * Throws { link RFC822Error.NOT_FOUND} if an HTML body is not present.
+     */
     public string? get_html_body(bool allow_only_replaced = false,
         InlinePartReplacer? replacer = null) throws RFC822Error {
         string? body = null;
         if (!construct_body_from_mime_parts(ref body, replacer, "html", allow_only_replaced))
             throw new RFC822Error.NOT_FOUND("Could not find any \"text/html\" parts");
+        
         return body;
     }
     
+    /**
+     * Returns the plaintext portion of the message body, if present.
+     *
+     * The allow_only_replaced flag indicates if it's allowable for the method to return only the
+     * InlinePartReplacer's returned text.  In other words, if only inline MIME section is found
+     * but no plaintext portion, allow_only_replaced indicates if the InlinePartReplacer's returned
+     * text constitutes a "body".
+     *
+     * The convert_to_html indicates if the plaintext body should be converted into HTML.  Note that
+     * the InlinePartReplacer's output is not converted; it's up to the caller to know what format
+     * to return when invoked.
+     *
+     * Throws { link RFC822Error.NOT_FOUND} if a plaintext body is not present.
+     */
     public string? get_text_body(bool convert_to_html = true, bool allow_only_replaced = false,
         InlinePartReplacer? replacer = null) throws RFC822Error {
         string? body = null;
         if (!construct_body_from_mime_parts(ref body, replacer, "plain", allow_only_replaced, 
convert_to_html))
             throw new RFC822Error.NOT_FOUND("Could not find any \"text/plain\" parts");
+        
         return body;
     }
     
-    // Returns a body of the email as HTML.  The "html_format" flag tells it whether to try for a
-    // HTML format body or plain text body first.  But if it doesn't find that one, it'll return
-    // the other.
+    /**
+     * Returns a body of the email as HTML.
+     *
+     * The html_format flag indicates whether to use the HTML portion of the message body or to
+     * convert the plaintext portion into HTML.  If the requested portion is not present, the
+     * method will fallback and attempt to return the other (converted to HTML, if necessary).
+     *
+     * Note that the InlinePartReplacer's output is never converted and should return HTML.
+     *
+     * Throws { link RFC822Error.NOT_FOUND if neither format is available.
+     */
     public string? get_body(bool html_format, InlinePartReplacer? replacer = null) throws RFC822Error {
         try {
             return html_format ? get_html_body(false, replacer) : get_text_body(true, false, replacer);