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

6 files changed, 53 insertions, 0 deletions

diff --git a/backends/eds/lib/edsf-persona-store.vala b/backends/eds/lib/edsf-persona-store.vala
index 4fa5b973..7c6c77e6 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 f440b9ff..bbddf572 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 6bb4b1d0..e8736ef5 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 998dc900..0256be29 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 54015043..12349c0e 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 f6858068..2441bfb2 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
     {