[geary/wip/714922-multiple-addresses-2] Update symbol names to be more specific to what they represent

[Jim Nelson <jnelson src gnome org>]

commit abcbf95bff3600ddc2d83ea054a02ec70c8c832b
Author: Jim Nelson <jim yorba org>
Date:   Wed Mar 4 15:56:30 2015 -0800

    Update symbol names to be more specific to what they represent
    
    Also adds some much-needed documentation to AccountInformation.

 .../account-dialog-edit-alternate-emails-pane.vala |    4 +-
 src/client/composer/composer-widget.vala           |   12 ++--
 .../conversation-list/conversation-list-store.vala |    2 +-
 src/engine/api/geary-account-information.vala      |   81 ++++++++++++--------
 4 files changed, 57 insertions(+), 42 deletions(-)
---
diff --git a/src/client/accounts/account-dialog-edit-alternate-emails-pane.vala 
b/src/client/accounts/account-dialog-edit-alternate-emails-pane.vala
index 25f583f..e621ee5 100644
--- a/src/client/accounts/account-dialog-edit-alternate-emails-pane.vala
+++ b/src/client/accounts/account-dialog-edit-alternate-emails-pane.vala
@@ -129,7 +129,7 @@ public class AccountDialogEditAlternateEmailsPane : AccountDialogPane {
             address_listbox.remove(widget);
         
         // Add all email addresses; add_email_address() silently drops the primary address
-        foreach (Geary.RFC822.MailboxAddress mailbox in account_info.get_all_email_addresses())
+        foreach (Geary.RFC822.MailboxAddress mailbox in account_info.get_all_mailboxes())
             add_mailbox(mailbox, false);
     }
     
@@ -197,7 +197,7 @@ public class AccountDialogEditAlternateEmailsPane : AccountDialogPane {
     }
     
     private void on_update_clicked() {
-        account_info.replace_alternate_emails(mailboxes);
+        account_info.replace_alternate_mailboxes(mailboxes);
         
         done();
     }
diff --git a/src/client/composer/composer-widget.vala b/src/client/composer/composer-widget.vala
index f71cf28..bc62249 100644
--- a/src/client/composer/composer-widget.vala
+++ b/src/client/composer/composer-widget.vala
@@ -736,7 +736,7 @@ public class ComposerWidget : Gtk.EventBox {
             if (referred.from != null)
                 from = referred.from;
         } else {
-            Gee.List<Geary.RFC822.MailboxAddress> account_addresses = 
account.information.get_all_email_addresses();
+            Gee.List<Geary.RFC822.MailboxAddress> account_addresses = 
account.information.get_all_mailboxes();
             if (!check_preferred_from_address(account_addresses, referred.to)) {
                 if (!check_preferred_from_address(account_addresses, referred.cc))
                     if (!check_preferred_from_address(account_addresses, referred.bcc))
@@ -989,7 +989,7 @@ public class ComposerWidget : Gtk.EventBox {
     
     private void add_recipients_and_ids(ComposeType type, Geary.Email referred,
         bool modify_headers = true) {
-        Gee.List<Geary.RFC822.MailboxAddress> sender_addresses = 
account.information.get_all_email_addresses();
+        Gee.List<Geary.RFC822.MailboxAddress> sender_addresses = account.information.get_all_mailboxes();
         Geary.RFC822.MailboxAddresses to_addresses =
             Geary.RFC822.Utils.create_to_addresses_for_reply(referred, sender_addresses);
         Geary.RFC822.MailboxAddresses cc_addresses =
@@ -2277,10 +2277,10 @@ public class ComposerWidget : Gtk.EventBox {
             set_active = true;
         }
         
-        if (account.information.alternate_emails != null) {
-            foreach (Geary.RFC822.MailboxAddress alternate_email in account.information.alternate_emails) {
+        if (account.information.alternate_mailboxes != null) {
+            foreach (Geary.RFC822.MailboxAddress alternate_mailbox in 
account.information.alternate_mailboxes) {
                 Geary.RFC822.MailboxAddresses addresses = new Geary.RFC822.MailboxAddresses.single(
-                    alternate_email);
+                    alternate_mailbox);
                 
                 // Displayed in the From dropdown to indicate an "alternate email address"
                 // for an account.  The first printf argument will be the alternate email
@@ -2318,7 +2318,7 @@ public class ComposerWidget : Gtk.EventBox {
         
         // If there's only one account, show nothing. (From fields are hidden above.)
         if (accounts.size < 1 || (accounts.size == 1 && Geary.traverse<Geary.AccountInformation>(
-            accounts.values).first().alternate_emails == null))
+            accounts.values).first().alternate_mailboxes == null))
             return;
         
         from_label.visible = true;
diff --git a/src/client/conversation-list/conversation-list-store.vala 
b/src/client/conversation-list/conversation-list-store.vala
index ebe2106..3dfb11c 100644
--- a/src/client/conversation-list/conversation-list-store.vala
+++ b/src/client/conversation-list/conversation-list-store.vala
@@ -287,7 +287,7 @@ public class ConversationListStore : Gtk.ListStore {
     private void set_row(Gtk.TreeIter iter, Geary.App.Conversation conversation, Geary.Email preview) {
         FormattedConversationData conversation_data = new FormattedConversationData(conversation,
             preview, conversation_monitor.folder,
-            conversation_monitor.folder.account.information.get_all_email_addresses());
+            conversation_monitor.folder.account.information.get_all_mailboxes());
         
         Gtk.TreePath? path = get_path(iter);
         assert(path != null);
diff --git a/src/engine/api/geary-account-information.vala b/src/engine/api/geary-account-information.vala
index af2d377..2623cb0 100644
--- a/src/engine/api/geary-account-information.vala
+++ b/src/engine/api/geary-account-information.vala
@@ -61,25 +61,41 @@ public class Geary.AccountInformation : BaseObject {
     
     internal File? file = null;
     
+    //
     // IMPORTANT: When adding new properties, be sure to add them to the copy method.
+    //
     
+    /**
+     * User's name for the { link primary_mailbox}.
+     */
     public string real_name { get; set; }
+    
+    /**
+     * User label for primary account (not transmitted on wire or used in correspondence).
+     */
     public string nickname { get; set; }
+    
     /**
      * The primary email address for the account.
      *
-     * @see get_all_email_addresses
+     * This the RFC822 simple mailbox style, i.e. "jim example com".
+     *
+     * In general, it's better to use the result of { link get_primary_mailbox_address}, as the
+     * { link Geary.RFC822.MailboxAddress} object is better suited for comparisons, Gee collections,
+     * validation, composing quoted strings, and so forth.
      */
     public string email { get; set; }
+    
     /**
      * A list of additional email addresses this account accepts.
      *
-     * Use { link add_alternate_email} or { link replace_alternate_emails} rather than edit this
-     * collection directly.
+     * Use { link add_alternate_mailbox} or { link replace_alternate_mailboxes} rather than edit
+     * this collection directly.
      *
-     * @see get_all_email_addresses
+     * @see get_all_mailboxes
      */
-    public Gee.List<Geary.RFC822.MailboxAddress>? alternate_emails { get; private set; }
+    public Gee.List<Geary.RFC822.MailboxAddress>? alternate_mailboxes { get; private set; }
+    
     public Geary.ServiceProvider service_provider { get; set; }
     public int prefetch_period_days { get; set; }
     
@@ -167,15 +183,12 @@ public class Geary.AccountInformation : BaseObject {
             // Store alternate emails in a list of case-insensitive strings
             Gee.List<string> alt_email_list = get_string_list_value(key_file, GROUP, ALTERNATE_EMAILS_KEY);
             if (alt_email_list.size == 0) {
-                alternate_emails = null;
+                alternate_mailboxes = null;
             } else {
-                alternate_emails = new Gee.ArrayList<RFC822.MailboxAddress>();
                 foreach (string alt_email in alt_email_list) {
                     RFC822.MailboxAddresses mailboxes = new 
RFC822.MailboxAddresses.from_rfc822_string(alt_email);
-                    foreach (RFC822.MailboxAddress mailbox in mailboxes.get_all()) {
-                        if (!alternate_emails.contains(mailbox))
-                            alternate_emails.add(mailbox);
-                    }
+                    foreach (RFC822.MailboxAddress mailbox in mailboxes.get_all())
+                        add_alternate_mailbox(mailbox);
                 }
             }
             
@@ -262,11 +275,10 @@ public class Geary.AccountInformation : BaseObject {
         real_name = from.real_name;
         nickname = from.nickname;
         email = from.email;
-        alternate_emails = null;
-        if (from.alternate_emails != null) {
-            alternate_emails = new Gee.ArrayList<RFC822.MailboxAddress>();
-            foreach (RFC822.MailboxAddress alternate_email in from.alternate_emails)
-                alternate_emails.add(alternate_email);
+        alternate_mailboxes = null;
+        if (from.alternate_mailboxes != null) {
+            foreach (RFC822.MailboxAddress alternate_mailbox in from.alternate_mailboxes)
+                add_alternate_mailbox(alternate_mailbox);
         }
         service_provider = from.service_provider;
         prefetch_period_days = from.prefetch_period_days;
@@ -298,11 +310,14 @@ public class Geary.AccountInformation : BaseObject {
     /**
      * Return a list of the primary and all alternate email addresses.
      */
-    public Gee.List<Geary.RFC822.MailboxAddress> get_all_email_addresses() {
+    public Gee.List<Geary.RFC822.MailboxAddress> get_all_mailboxes() {
         Gee.ArrayList<RFC822.MailboxAddress> all = new Gee.ArrayList<RFC822.MailboxAddress>();
+        
         all.add(get_primary_mailbox_address());
-        if (alternate_emails != null)
-            all.add_all(alternate_emails);
+        
+        if (alternate_mailboxes != null)
+            all.add_all(alternate_mailboxes);
+        
         return all;
     }
     
@@ -311,12 +326,12 @@ public class Geary.AccountInformation : BaseObject {
      *
      * Duplicates will be ignored.
      */
-    public void add_alternate_email(Geary.RFC822.MailboxAddress email) {
-        if (alternate_emails == null)
-            alternate_emails = new Gee.ArrayList<RFC822.MailboxAddress>();
+    public void add_alternate_mailbox(Geary.RFC822.MailboxAddress mailbox) {
+        if (alternate_mailboxes == null)
+            alternate_mailboxes = new Gee.ArrayList<RFC822.MailboxAddress>();
         
-        if (!alternate_emails.contains(email))
-            alternate_emails.add(email);
+        if (!alternate_mailboxes.contains(mailbox))
+            alternate_mailboxes.add(mailbox);
     }
     
     /**
@@ -324,14 +339,14 @@ public class Geary.AccountInformation : BaseObject {
      *
      * Duplicates will be ignored.
      */
-    public void replace_alternate_emails(Gee.Collection<Geary.RFC822.MailboxAddress>? emails) {
-        alternate_emails = null;
+    public void replace_alternate_mailboxes(Gee.Collection<Geary.RFC822.MailboxAddress>? mailboxes) {
+        alternate_mailboxes = null;
         
-        if (emails == null || emails.size == 0)
+        if (mailboxes == null || mailboxes.size == 0)
             return;
         
-        foreach (RFC822.MailboxAddress email in emails)
-            add_alternate_email(email);
+        foreach (RFC822.MailboxAddress mailbox in mailboxes)
+            add_alternate_mailbox(mailbox);
     }
     
     /**
@@ -788,10 +803,10 @@ public class Geary.AccountInformation : BaseObject {
         key_file.set_boolean(GROUP, SAVE_SENT_MAIL_KEY, save_sent_mail);
         key_file.set_boolean(GROUP, USE_EMAIL_SIGNATURE_KEY, use_email_signature);
         key_file.set_string(GROUP, EMAIL_SIGNATURE_KEY, email_signature);
-        if (alternate_emails != null && alternate_emails.size > 0) {
-            string[] list = new string[alternate_emails.size];
-            for (int ctr = 0; ctr < alternate_emails.size; ctr++)
-                list[ctr] = alternate_emails[ctr].to_rfc822_string();
+        if (alternate_mailboxes != null && alternate_mailboxes.size > 0) {
+            string[] list = new string[alternate_mailboxes.size];
+            for (int ctr = 0; ctr < alternate_mailboxes.size; ctr++)
+                list[ctr] = alternate_mailboxes[ctr].to_rfc822_string();
             
             key_file.set_string_list(GROUP, ALTERNATE_EMAILS_KEY, list);
         }