[folks] Bug 663890 â @throws annotations missing for some functions

[Philip Withnall <pwithnall src gnome org>]

commit 186a237ba31d9bb392a48511ab2b95bdb4352d2c
Author: Philip Withnall <philip tecnocode co uk>
Date:   Tue Apr 24 00:02:43 2012 +0100

    Bug 663890 â @throws annotations missing for some functions
    
    Add missing â throwsâ annotations to various public methods.
    
    Closes: https://bugzilla.gnome.org/show_bug.cgi?id=663890

 NEWS                                             |    1 +
 backends/eds/lib/edsf-persona-store.vala         |   18 +++++++++++++
 backends/key-file/kf-persona-store.vala          |    3 ++
 backends/libsocialweb/lib/swf-persona-store.vala |   10 +++++++
 backends/telepathy/lib/tpf-persona-store.vala    |   12 +++++++++
 backends/telepathy/lib/tpf-persona.vala          |    3 ++
 backends/tracker/lib/trf-persona-store.vala      |    7 +++++
 folks/backend-store.vala                         |    2 +
 folks/backend.vala                               |    4 +++
 folks/group-details.vala                         |    2 +
 folks/individual-aggregator.vala                 |   29 ++++++++++++++++++++++
 folks/persona-store.vala                         |    6 ++++
 12 files changed, 97 insertions(+), 0 deletions(-)
---
diff --git a/NEWS b/NEWS
index bf6ae89..e0ab5c3 100644
--- a/NEWS
+++ b/NEWS
@@ -10,6 +10,7 @@ Dependencies:
 Bugs fixed:
 â Bug 674256 â telepathy-glib minimal version is insufficient
 â Bug 647909 â Port Folks to GSettings
+â Bug 663890 â @throws annotations missing for some functions
 
 Overview of changes from libfolks 0.6.9 to libfolks 0.7.0
 =========================================================
diff --git a/backends/eds/lib/edsf-persona-store.vala b/backends/eds/lib/edsf-persona-store.vala
index 4fa5b97..7c6c77e 100644
--- a/backends/eds/lib/edsf-persona-store.vala
+++ b/backends/eds/lib/edsf-persona-store.vala
@@ -299,6 +299,11 @@ public class Edsf.PersonaStore : Folks.PersonaStore
    *
    * See { link Folks.PersonaStore.add_persona_from_details}.
    *
+   * @throws Folks.PersonaStoreError.STORE_OFFLINE if the store hasnât been
+   * prepared
+   * @throws Folks.PersonaStoreError.CREATE_FAILED if creating the persona in
+   * the EDS store failed
+   *
    * @since 0.6.0
    */
   public override async Folks.Persona? add_persona_from_details (
@@ -489,6 +494,13 @@ public class Edsf.PersonaStore : Folks.PersonaStore
    * See { link Folks.PersonaStore.remove_persona}.
    *
    * @param persona the persona that should be removed
+   * @throws Folks.PersonaStoreError.STORE_OFFLINE if the store hasnât been
+   * prepared or has gone offline
+   * @throws Folks.PersonaStoreError.PERMISSION_DENIED if the store denied
+   * permission to delete the contact
+   * @throws Folks.PersonaStoreError.READ_ONLY if the store is read only
+   * @throws Folks.PersonaStoreError.REMOVE_FAILED if any other errors happened
+   * in the store
    *
    * @since 0.6.0
    */
@@ -585,6 +597,12 @@ public class Edsf.PersonaStore : Folks.PersonaStore
    *
    * See { link Folks.PersonaStore.prepare}.
    *
+   * @throws Folks.PersonaStoreError.STORE_OFFLINE if the EDS store is offline
+   * @throws Folks.PersonaStoreError.PERMISSION_DENIED if permission was denied
+   * to open the EDS store
+   * @throws Folks.PersonaStoreError.INVALID_ARGUMENT if any other error
+   * occurred in the EDS store
+   *
    * @since 0.6.0
    */
   public override async void prepare () throws PersonaStoreError
diff --git a/backends/key-file/kf-persona-store.vala b/backends/key-file/kf-persona-store.vala
index f440b9f..bbddf57 100644
--- a/backends/key-file/kf-persona-store.vala
+++ b/backends/key-file/kf-persona-store.vala
@@ -356,6 +356,9 @@ public class Folks.Backends.Kf.PersonaStore : Folks.PersonaStore
    * - PersonaStore.detail_key (PersonaDetail.WEB_SERVICE_ADDRESSES)
    *
    * See { link Folks.PersonaStore.add_persona_from_details}.
+   *
+   * @throws Folks.PersonaStoreError.CREATE_FAILED if setting the personaâs
+   * properties failed
    */
   public override async Folks.Persona? add_persona_from_details (
       HashTable<string, Value?> details) throws Folks.PersonaStoreError
diff --git a/backends/libsocialweb/lib/swf-persona-store.vala b/backends/libsocialweb/lib/swf-persona-store.vala
index 6bb4b1d..e8736ef 100644
--- a/backends/libsocialweb/lib/swf-persona-store.vala
+++ b/backends/libsocialweb/lib/swf-persona-store.vala
@@ -195,6 +195,9 @@ public class Swf.PersonaStore : Folks.PersonaStore
    * Add a new { link Persona} to the PersonaStore.
    *
    * See { link Folks.PersonaStore.add_persona_from_details}.
+   *
+   * @throws Folks.PersonaStoreError.READ_ONLY every time â libsocialweb is
+   * read-only
    */
   public override async Folks.Persona? add_persona_from_details (
       HashTable<string, Value?> details) throws Folks.PersonaStoreError
@@ -207,6 +210,9 @@ public class Swf.PersonaStore : Folks.PersonaStore
    * Remove a { link Persona} from the PersonaStore.
    *
    * See { link Folks.PersonaStore.remove_persona}.
+   *
+   * @throws Folks.PersonaStoreError.READ_ONLY every time â libsocialweb is
+   * read-only
    */
   public override async void remove_persona (Folks.Persona persona)
       throws Folks.PersonaStoreError
@@ -303,6 +309,10 @@ public class Swf.PersonaStore : Folks.PersonaStore
    * Prepare the PersonaStore for use.
    *
    * See { link Folks.PersonaStore.prepare}.
+   *
+   * @throws Folks.PersonaStoreError.INVALID_ARGUMENT if the libsocialweb
+   * service capabilities couldnât be retrieved, or if the âcontactsâ capability
+   * wasnât found, or if a view couldnât be opened
    */
   public override async void prepare () throws GLib.Error
     {
diff --git a/backends/telepathy/lib/tpf-persona-store.vala b/backends/telepathy/lib/tpf-persona-store.vala
index 998dc90..0256be2 100644
--- a/backends/telepathy/lib/tpf-persona-store.vala
+++ b/backends/telepathy/lib/tpf-persona-store.vala
@@ -417,6 +417,8 @@ public class Tpf.PersonaStore : Folks.PersonaStore
    * Prepare the PersonaStore for use.
    *
    * See { link Folks.PersonaStore.prepare}.
+   *
+   * @throws GLib.Error currently unused
    */
   public override async void prepare () throws GLib.Error
     {
@@ -1079,6 +1081,11 @@ public class Tpf.PersonaStore : Folks.PersonaStore
    * Remove a { link Persona} from the PersonaStore.
    *
    * See { link Folks.PersonaStore.remove_persona}.
+   *
+   * @throws Folks.PersonaStoreError.UNSUPPORTED_ON_USER if `persona` is the
+   * local user â removing the local user isnât supported
+   * @throws Folks.PersonaStoreError.REMOVE_FAILED if removing the contact
+   * failed
    */
   public override async void remove_persona (Folks.Persona persona)
       throws Folks.PersonaStoreError
@@ -1125,6 +1132,11 @@ public class Tpf.PersonaStore : Folks.PersonaStore
    * Add a new { link Persona} to the PersonaStore.
    *
    * See { link Folks.PersonaStore.add_persona_from_details}.
+   *
+   * @throws Folks.PersonaStoreError.INVALID_ARGUMENT if the `contact` key was
+   * not provided in `details`
+   * @throws Folks.PersonaStoreError.STORE_OFFLINE if the CM is offline
+   * @throws Folks.PersonaStoreError.CREATE_FAILED if adding the contact failed
    */
   public override async Folks.Persona? add_persona_from_details (
       HashTable<string, Value?> details) throws Folks.PersonaStoreError
diff --git a/backends/telepathy/lib/tpf-persona.vala b/backends/telepathy/lib/tpf-persona.vala
index 5401504..12349c0 100644
--- a/backends/telepathy/lib/tpf-persona.vala
+++ b/backends/telepathy/lib/tpf-persona.vala
@@ -407,6 +407,9 @@ public class Tpf.Persona : Folks.Persona,
    * Add or remove the Persona from the specified group.
    *
    * See { link Folks.GroupDetails.change_group}.
+   *
+   * @throws Folks.PropertyError.UNKNOWN_ERROR if changing group membership
+   * failed
    */
   public async void change_group (string group, bool is_member)
       throws GLib.Error
diff --git a/backends/tracker/lib/trf-persona-store.vala b/backends/tracker/lib/trf-persona-store.vala
index f685806..2441bfb 100644
--- a/backends/tracker/lib/trf-persona-store.vala
+++ b/backends/tracker/lib/trf-persona-store.vala
@@ -448,6 +448,9 @@ public class Trf.PersonaStore : Folks.PersonaStore
    * - PersonaStore.detail_key (PersonaDetail.WEB_SERVICE_ADDRESSES)
    *
    * See { link Folks.PersonaStore.add_persona_from_details}.
+   *
+   * @throws Folks.PersonaStoreError.INVALID_ARGUMENT if an unrecognised detail
+   * key was passed in `details`
    */
   public override async Folks.Persona? add_persona_from_details (
       HashTable<string, Value?> details) throws Folks.PersonaStoreError
@@ -889,6 +892,7 @@ public class Trf.PersonaStore : Folks.PersonaStore
    *
    * See { link Folks.PersonaStore.remove_persona}.
    *
+   * @throws Folks.PersonaStoreError currently unused
    */
   public override async void remove_persona (Folks.Persona persona)
       throws Folks.PersonaStoreError
@@ -1057,6 +1061,9 @@ public class Trf.PersonaStore : Folks.PersonaStore
    *       when we were trying to setup the PersonaStore.
    *
    * See { link Folks.PersonaStore.prepare}.
+   *
+   * @throws Folks.PersonaStoreError.INVALID_ARGUMENT if connecting to D-Bus
+   * failed
    */
   public override async void prepare () throws GLib.Error
     {
diff --git a/folks/backend-store.vala b/folks/backend-store.vala
index 6866eee..cad02fe 100644
--- a/folks/backend-store.vala
+++ b/folks/backend-store.vala
@@ -270,6 +270,8 @@ public class Folks.BackendStore : Object {
    * Backends will be searched for in the path given by the `FOLKS_BACKEND_PATH`
    * environment variable, if it's set. If it's not set, backends will be
    * searched for in a path set at compilation time.
+   *
+   * @throws GLib.Error currently unused
    */
   public async void load_backends () throws GLib.Error
     {
diff --git a/folks/backend.vala b/folks/backend.vala
index a4b7c5b..89f7264 100644
--- a/folks/backend.vala
+++ b/folks/backend.vala
@@ -133,6 +133,8 @@ public abstract class Folks.Backend : Object
    * other respect.)
    *
    * @since 0.1.11
+   * @throws GLib.Error if preparing the backend-specific services failed â this
+   * will be a backend-specific error
    */
   public abstract async void prepare () throws GLib.Error;
 
@@ -155,6 +157,8 @@ public abstract class Folks.Backend : Object
    * other respect.)
    *
    * @since 0.3.2
+   * @throws GLib.Error if unpreparing the backend-specific services failed â
+   * this will be a backend-specific error
    */
   public abstract async void unprepare () throws GLib.Error;
 }
diff --git a/folks/group-details.vala b/folks/group-details.vala
index fc73fff..269a5ee 100644
--- a/folks/group-details.vala
+++ b/folks/group-details.vala
@@ -131,6 +131,8 @@ public interface Folks.GroupDetails : Object
    *
    * @param group a freeform group identifier
    * @param is_member whether the contact should be a member of the group
+   * @throws GLib.Error if changing the group failed in the backing store
+   *
    * @since 0.1.11
    */
   public async abstract void change_group (string group, bool is_member)
diff --git a/folks/individual-aggregator.vala b/folks/individual-aggregator.vala
index cfeabff..cf5415e 100644
--- a/folks/individual-aggregator.vala
+++ b/folks/individual-aggregator.vala
@@ -489,6 +489,9 @@ public class Folks.IndividualAggregator : Object
    * calls might return before the first one. (Though they will be safe in every
    * other respect.)
    *
+   * @throws GLib.Error if preparing any of the backends failed â this error
+   * will be passed through from { link BackendStore.load_backends}
+   *
    * @since 0.1.11
    */
   public async void prepare () throws GLib.Error
@@ -1598,6 +1601,10 @@ public class Folks.IndividualAggregator : Object
    * @return the new { link Persona} or `null` if the corresponding
    * { link Persona} already existed. If non-`null`, the new { link Persona}
    * will also be added to a new or existing { link Individual} as necessary.
+   * @throws IndividualAggregatorError.STORE_OFFLINE if the persona store was
+   * offline
+   * @throws IndividualAggregatorError.ADD_FAILED if any other error occurred
+   * while adding the persona
    *
    * @since 0.3.5
    */
@@ -1655,6 +1662,9 @@ public class Folks.IndividualAggregator : Object
    * backing stores.
    *
    * @param individual the { link Individual} to remove
+   * @throws GLib.Error if removing the persona failed â this will be passed
+   * through from { link PersonaStore.remove_persona}
+   *
    * @since 0.1.11
    */
   public async void remove_individual (Individual individual) throws GLib.Error
@@ -1679,6 +1689,9 @@ public class Folks.IndividualAggregator : Object
    * This will leave other personas in the same individual alone.
    *
    * @param persona the { link Persona} to remove
+   * @throws GLib.Error if removing the persona failed â this will be passed
+   * through from { link PersonaStore.remove_persona}
+   *
    * @since 0.1.11
    */
   public async void remove_persona (Persona persona) throws GLib.Error
@@ -1698,6 +1711,12 @@ public class Folks.IndividualAggregator : Object
    * { link Individual.removed}.
    *
    * @param personas the { link Persona}s to be linked
+   * @throws IndividualAggregatorError.NO_PRIMARY_STORE if no primary store has
+   * been configured for the individual aggregator
+   * @throws IndividualAggregatorError if adding the linking persona failed â
+   * this will be passed through from
+   * { link IndividualAggregator.add_persona_from_details}
+   *
    * @since 0.5.1
    */
   public async void link_personas (Set<Persona> personas)
@@ -1838,6 +1857,9 @@ public class Folks.IndividualAggregator : Object
    * { link IndividualAggregator.individuals_changed}.
    *
    * @param individual the { link Individual} to unlink
+   * @throws GLib.Error if removing the linking persona failed â this will be
+   * passed through from { link PersonaStore.remove_persona}
+   *
    * @since 0.1.13
    */
   public async void unlink_individual (Individual individual) throws GLib.Error
@@ -1900,6 +1922,13 @@ public class Folks.IndividualAggregator : Object
    * (this should be in lower case using hyphens, e.g. âweb-service-addressesâ)
    * @return a persona (new or existing) which has the given property as
    * writeable
+   * @throws IndividualAggregatorError.NO_PRIMARY_STORE if no primary store was
+   * configured for this individual aggregator
+   * @throws IndividualAggregatorError.PROPERTY_NOT_WRITEABLE if the given
+   * `property_name` referred to a non-writeable property
+   * @throws IndividualAggregatorError if adding a new persona (using
+   * { link IndividualAggregator.add_persona_from_details}) failed, or if
+   * linking personas (using { link IndividualAggregator.link_personas}) failed
    *
    * @since 0.6.2
    */
diff --git a/folks/persona-store.vala b/folks/persona-store.vala
index 4b302da..b5758d6 100644
--- a/folks/persona-store.vala
+++ b/folks/persona-store.vala
@@ -597,6 +597,9 @@ public abstract class Folks.PersonaStore : Object
    * calls might return before the first one. (Though they will be safe in every
    * other respect.)
    *
+   * @throws GLib.Error if preparing the backend-specific services failed â this
+   * will be a backend-specific error
+   *
    * @since 0.1.11
    */
   public abstract async void prepare () throws GLib.Error;
@@ -650,6 +653,7 @@ public abstract class Folks.PersonaStore : Object
    * already existed. If non-`null`, the new { link Persona} will also be
    * amongst the { link Persona}(s) in a future emission of
    * { link PersonaStore.personas_changed}.
+   * @throws PersonaStoreError if adding the persona failed
    */
   public abstract async Persona? add_persona_from_details (
       HashTable<string, Value?> details) throws Folks.PersonaStoreError;
@@ -669,6 +673,8 @@ public abstract class Folks.PersonaStore : Object
    * offline removals work.
    *
    * @param persona the { link Persona} to remove
+   * @throws PersonaStoreError if removing the persona failed
+   *
    * @since 0.1.11
    */
   public abstract async void remove_persona (Persona persona)