[geary/wip/create-folders-713492] Add/clarify comments

[Charles Lindsay <clindsay src gnome org>]

commit 3e40d156d17e62ee7f67278b603f6cdfabc5b2eb
Author: Charles Lindsay <chaz yorba org>
Date:   Mon Feb 10 16:25:53 2014 -0800

    Add/clarify comments

 src/engine/api/geary-account-information.vala |   13 +++++++++++++
 src/engine/api/geary-account.vala             |    8 ++++----
 2 files changed, 17 insertions(+), 4 deletions(-)
---
diff --git a/src/engine/api/geary-account-information.vala b/src/engine/api/geary-account-information.vala
index 00183ff..6955ed1 100644
--- a/src/engine/api/geary-account-information.vala
+++ b/src/engine/api/geary-account-information.vala
@@ -202,6 +202,13 @@ public class Geary.AccountInformation : BaseObject {
         return service_provider != ServiceProvider.GMAIL;
     }
     
+    /**
+     * Gets the path used when Geary has found or created a special folder for
+     * this account.  This will be null if Geary has always been told about the
+     * special folders by the server, and hasn't had to go looking for them.
+     * Only the DRAFTS, SENT, SPAM, and TRASH special folder types are valid to
+     * pass to this function.
+     */
     public Geary.FolderPath? get_special_folder_path(Geary.SpecialFolderType special) {
         switch (special) {
             case Geary.SpecialFolderType.DRAFTS:
@@ -221,6 +228,12 @@ public class Geary.AccountInformation : BaseObject {
         }
     }
     
+    /**
+     * Sets the path Geary will look for or create a special folder.  This is
+     * only obeyed if the server doesn't tell Geary which folders are special.
+     * Only the DRAFTS, SENT, SPAM, and TRASH special folder types are valid to
+     * pass to this function.
+     */
     public void set_special_folder_path(Geary.SpecialFolderType special, Geary.FolderPath? path) {
         switch (special) {
             case Geary.SpecialFolderType.DRAFTS:
diff --git a/src/engine/api/geary-account.vala b/src/engine/api/geary-account.vala
index 8c47ad3..a144566 100644
--- a/src/engine/api/geary-account.vala
+++ b/src/engine/api/geary-account.vala
@@ -280,10 +280,10 @@ public interface Geary.Account : BaseObject {
     public abstract Geary.Folder? get_special_folder(Geary.SpecialFolderType special) throws Error;
     
     /**
-     * Returns the folder with the given special folder type.  The folder will be created if it
-     * doesn't already exist.  An error will be thrown if the folder doesn't exist and can't be
-     * created.  The only valid special folder types that can be required are: DRAFTS, SENT,
-     * SPAM, and TRASH.
+     * Returns the Folder object with the given special folder type.  The folder will be
+     * created on the server if it doesn't already exist.  An error will be thrown if the
+     * folder doesn't exist and can't be created.  The only valid special folder types that
+     * can be required are: DRAFTS, SENT, SPAM, and TRASH.
      */
     public abstract async Geary.Folder get_required_special_folder_async(Geary.SpecialFolderType special,
         Cancellable? cancellable = null) throws Error;