Commit 186a237b authored by Philip Withnall's avatar Philip Withnall
Browse files

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
parent cacb8622
......@@ -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
=========================================================
......
......@@ -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
......
......@@ -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
......
......@@ -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
{
......
......@@ -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
......
......@@ -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
......
......@@ -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
{
......
......@@ -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
{
......
......@@ -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;
}
......@@ -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)
......
......@@ -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
*/
......
......@@ -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)
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment