Commit c93131b6 authored by Philip Withnall's avatar Philip Withnall
Browse files

docs: Fix up lots of minor issues in the documentation comments

parent 556fb7b3
......@@ -22,8 +22,8 @@ using GLib;
/**
* A wrapper around a blob of image data (with an associated content type) which
* presents it as a {@link LoadableIcon}. This allows inlined avatars to be
* returned as {@link LoadableIcon}s.
* presents it as a {@link GLib.LoadableIcon}. This allows inlined avatars to be
* returned as {@link GLib.LoadableIcon}s.
*
* @since UNRELEASED
*/
......
......@@ -157,8 +157,8 @@ public class Folks.AvatarCache : Object
/**
* Remove an avatar from the cache, if it exists in the cache. If the avatar
* exists in the cache but there is a problem in removing it, an
* {@link IOError} will be thrown.
* exists in the cache but there is a problem in removing it, a
* {@link GLib.Error} will be thrown.
*
* @param id the globally unique ID for the avatar
* @throws GLib.Error if deleting the cache file failed
......
......@@ -31,7 +31,7 @@ public interface Folks.AvatarDetails : Object
*
* An avatar is a small image file which represents the contact. It may be
* `null` if unset. Otherwise, the image data may be asynchronously loaded
* using the methods of the {@link LoadableIcon} implementation.
* using the methods of the {@link GLib.LoadableIcon} implementation.
*
* @since UNRELEASED
*/
......
......@@ -335,6 +335,12 @@ public class Folks.IndividualAggregator : Object
/**
* Get all matches for a given {@link Individual}.
*
* @param matchee the individual to find matches for
* @param min_threshold the threshold for accepting a match
* @return a map from matched individuals to the degree with which they match
* `matchee` (which is guaranteed to at least equal `min_threshold`);
* if no matches could be found, an empty map is returned
*
* @since 0.5.1
*/
public Map<Individual, MatchResult> get_potential_matches
......@@ -362,6 +368,12 @@ public class Folks.IndividualAggregator : Object
/**
* Get all combinations between all {@link Individual}s.
*
* @param min_threshold the threshold for accepting a match
* @return a map from each individual in the aggregator to a map of the
* other individuals in the aggregator which can be matched with that
* individual, mapped to the degree with which they match the original
* individual (which is guaranteed to at least equal `min_threshold`)
*
* @since 0.5.1
*/
public Map<Individual, Map<Individual, MatchResult>>
......
......@@ -140,8 +140,8 @@ public class Folks.Individual : Object,
/**
* Whether the Individual is the user.
*
* Iff the Individual represents the user (the person who owns the
* account in the backend for each {@link Persona} in the Individual)
* Iff the Individual represents the user the person who owns the
* account in the backend for each {@link Persona} in the Individual
* this is `true`.
*
* It is //not// guaranteed that every {@link Persona} in the Individual has
......
......@@ -167,6 +167,7 @@ public class Folks.StructuredName : Object
/**
* Whether two StructuredNames are the same.
*
* @param other the other structured name to compare with
* @return `true` if all the components are the same, `false`
* otherwise.
*
......
......@@ -61,6 +61,10 @@ public class Folks.Note : Object
/**
* Compare if 2 notes are equal. This compares both their {@link Note.content}
* and {@link Note.uid} (if set).
*
* @param a a note to compare
* @param b another note to compare
* @return `true` if the roles are equal, `false` otherwise
*/
public static bool equal (Note a, Note b)
{
......@@ -68,7 +72,10 @@ public class Folks.Note : Object
}
/**
* Hash function for the class.
* Hash function for the class. Suitable for use as a hash table key.
*
* @param r a note to hash
* @return hash value for the note instance
*/
public static uint hash (Note r)
{
......
......@@ -25,7 +25,7 @@ using Gee;
* A generic abstract cache for sets of objects. This can be used by subclasses
* to implement caching of homogeneous sets of objects. Subclasses simply have
* to implement serialisation and deserialisation of the objects to and from
* {@link Variant}s.
* {@link GLib.Variant}s.
*
* It's intended that this class be used for providing caching layers for
* {@link PersonaStore}s, for example.
......@@ -56,7 +56,7 @@ public abstract class Folks.ObjectCache<T> : Object
private File _cache_file;
/**
* Get the {@link VariantType} of the serialised form of an object stored
* Get the {@link GLib.VariantType} of the serialised form of an object stored
* in this cache.
*
* If a smooth upgrade path is needed in future due to cache file format
......@@ -77,9 +77,12 @@ public abstract class Folks.ObjectCache<T> : Object
protected abstract uint8 get_serialised_object_version ();
/**
* Serialise the given `object` to a {@link Variant} and return the variant.
* The variant must be of the type returned by
* {@link ObjectCache.get_serialised_object_type()}.
* Serialise the given `object` to a {@link GLib.Variant} and return the
* variant. The variant must be of the type returned by
* {@link ObjectCache.get_serialised_object_type}.
*
* @param object the object to serialise
* @return serialised form of `object`
*
* @since UNRELEASED
*/
......@@ -88,7 +91,10 @@ public abstract class Folks.ObjectCache<T> : Object
/**
* Deserialise the given `variant` to a new instance of an object. The variant
* is guaranteed to have the type returned by
* {@link ObjectCache.get_serialised_object_type()}.
* {@link ObjectCache.get_serialised_object_type}.
*
* @param variant the serialised form to deserialise
* @return the deserialised object
*
* @since UNRELEASED
*/
......@@ -138,7 +144,7 @@ public abstract class Folks.ObjectCache<T> : Object
* If any errors are encountered while loading the objects, warnings will be
* logged as appropriate and `null` will be returned.
*
* @param cancellable A {@link Cancellable} for the operation, or `null`.
* @param cancellable A {@link GLib.Cancellable} for the operation, or `null`.
* @return A set of objects from the cache, or `null`.
*
* @since UNRELEASED
......@@ -270,7 +276,7 @@ public abstract class Folks.ObjectCache<T> : Object
*
* @param objects A set of objects to store. This may be empty, but may not
* be `null`.
* @cancellable A {@link Cancellable} for the operation, or `null`.
* @param cancellable A {@link GLib.Cancellable} for the operation, or `null`.
*
* @since UNRELEASED
*/
......
......@@ -127,22 +127,123 @@ public errordomain Folks.PersonaStoreError
* {@link Folks.PersonaStore._PERSONA_DETAIL}. */
public enum Folks.PersonaDetail
{
/**
* Field for {@link AliasDetails.alias}.
*
* @since 0.5.0
*/
ALIAS,
/**
* Field for {@link AvatarDetails.avatar}.
*
* @since 0.5.0
*/
AVATAR,
/**
* Field for {@link BirthdayDetails.birthday}.
*
* @since 0.5.0
*/
BIRTHDAY,
/**
* Field for {@link EmailDetails.email_addresses}.
*
* @since 0.5.0
*/
EMAIL_ADDRESSES,
/**
* Field for {@link NameDetails.full_name}.
*
* @since 0.5.0
*/
FULL_NAME,
/**
* Field for {@link GenderDetails.gender}.
*
* @since 0.5.0
*/
GENDER,
/**
* Field for {@link ImDetails.im_addresses}.
*
* @since 0.5.0
*/
IM_ADDRESSES,
/**
* Field for {@link FavouriteDetails.is_favourite}.
*
* @since 0.5.0
*/
IS_FAVOURITE,
/**
* Field for {@link LocalIdDetails.local_ids}.
*
* @since 0.5.0
*/
LOCAL_IDS,
/**
* Field for {@link NameDetails.nickname}.
*
* @since 0.5.0
*/
NICKNAME,
/**
* Field for {@link NoteDetails.notes}.
*
* @since 0.5.0
*/
NOTES,
/**
* Field for {@link PhoneDetails.phone_numbers}.
*
* @since 0.5.0
*/
PHONE_NUMBERS,
/**
* Field for {@link PostalAddressDetails.postal_addresses}.
*
* @since 0.5.0
*/
POSTAL_ADDRESSES,
/**
* Field for {@link RoleDetails.roles}.
*
* @since 0.5.0
*/
ROLES,
/**
* Field for {@link NameDetails.structured_name}.
*
* @since 0.5.0
*/
STRUCTURED_NAME,
/**
* Field for {@link UrlDetails.urls}.
*
* @since 0.5.0
*/
URLS,
/**
* Field for {@link WebServiceDetails.web_service_addresses}.
*
* @since 0.5.0
*/
WEB_SERVICE_ADDRESSES
}
......@@ -160,7 +261,7 @@ public abstract class Folks.PersonaStore : Object
/**
* The following list of properties are the basic keys
* that each PersonaStore with write capabilities should
* support for {@link Persona.add_persona_from_details}.
* support for {@link PersonaStore.add_persona_from_details}.
*
* Note that these aren't the only valid keys; backends are
* allowed to support keys beyond the ones defined here
......@@ -192,7 +293,7 @@ public abstract class Folks.PersonaStore : Object
/**
* Returns the key corresponding to @detail, for use in
* the details param of {@link Persona.add_persona_from_details}.
* the details param of {@link PersonaStore.add_persona_from_details}.
*
* @param detail the {@link PersonaDetail} to lookup
*
......
......@@ -47,6 +47,11 @@ public interface Folks.PhoneDetails : Object
/**
* Normalise and compare two phone numbers.
*
* @param number1 a phone number to compare
* @param number2 another phone number to compare
* @return `true` if the phone numbers are equal, `false` otherwise
*
* @since 0.5.0
*/
public static bool numbers_equal (string number1, string number2)
......@@ -75,10 +80,12 @@ public interface Folks.PhoneDetails : Object
* Normalise a given phone number.
*
* Typical normalisations:
* - `1-800-123-4567` → `18001234567`
* - `+1-800-123-4567` → `18001234567`
* - `+1-800-123-4567P123` → `18001234567P123`
*
* - 1-800-123-4567 --> 18001234567
* - +1-800-123-4567 --> 18001234567
* - +1-800-123-4567P123 --> 18001234567P123
* @param number the phone number to normalise
* @return the normalised form of `number`
*
* @since 0.5.0
*/
......@@ -130,7 +137,11 @@ public interface Folks.PhoneDetails : Object
}
/**
* Returns the given number without it's extension (if any).
* Returns the given number without its extension (if any).
*
* @param number the phone number to process
* @return the number without its extension; if the number didn't have an
* extension in the first place, the number is returned unmodified
*
* @since 0.5.0
*/
......
......@@ -173,7 +173,10 @@ public class Folks.PostalAddress : Object
* @param locality the locality (city, town or village) name
* @param region the region (state or province) name
* @param postal_code the postal code
* @param country the country name
* @param address_format the address format
* @param types set of types for the address (such as "personal" or "work")
* @param uid external UID for the address instance
* @since 0.5.1
*/
public PostalAddress (string? po_box, string? extension, string? street,
......@@ -192,6 +195,14 @@ public class Folks.PostalAddress : Object
uid: uid);
}
/**
* Compare if two postal addresses are equal. Addresses are equal if all their
* components are equal (where `null` compares equal only with `null`) and
* they have the same set of types (or both have no types).
*
* @param with another postal address to compare with
* @return `true` if the addresses are equal, `false` otherwise
*/
public bool equal (PostalAddress with)
{
if (this.po_box != with.po_box ||
......@@ -218,7 +229,10 @@ public class Folks.PostalAddress : Object
}
/**
* Returns a formatted address.
* Get a formatted version of the address. The format is localised, and by
* default is comma-separated.
*
* @return a formatted address.
*
* @since 0.4.0
*/
......
......@@ -24,15 +24,44 @@ using Gee;
* Likely-ness of a potential match.
*
* Note that the order should be maintained.
*
* @since 0.5.0
*/
public enum Folks.MatchResult
{
/**
* Very low likelihood of a match.
*/
VERY_LOW,
/**
* Low likelihood of a match.
*/
LOW,
/**
* Medium likelihood of a match.
*/
MEDIUM,
/**
* High likelihood of a match.
*/
HIGH,
/**
* Very high likelihood of a match.
*/
VERY_HIGH,
/**
* Minimum likelihood of a match.
*/
MIN = VERY_LOW,
/**
* Maximum likelihood of a match.
*/
MAX = VERY_HIGH
}
......@@ -74,6 +103,9 @@ public class Folks.PotentialMatch : Object
/**
* Whether two individuals are likely to be the same person.
*
* @param a an individual to compare
* @param b another individual to compare
*
* @since 0.5.0
*/
public MatchResult potential_match (Individual a, Individual b)
......
......@@ -78,7 +78,12 @@ public class Folks.Role : Object
}
/**
* Compare if 2 roles are equal
* Compare if two roles are equal. Roles are equal if their titles and
* organisation names are equal.
*
* @param a a role to compare
* @param b another role to compare
* @return `true` if the roles are equal, `false` otherwise
*/
public static bool equal (Role a, Role b)
{
......@@ -87,7 +92,10 @@ public class Folks.Role : Object
}
/**
* Hash function for the class.
* Hash function for the class. Suitable for use as a hash table key.
*
* @param r a role to hash
* @return hash value for the role instance
*/
public static uint hash (Role r)
{
......
......@@ -28,6 +28,17 @@ public class Folks.Utils : Object
return (a != "" && b != "" && a.down () == b.down ());
}
/**
* Check whether two multi-maps of strings to strings are equal. This performs
* a deep check for equality, checking whether both maps are of the same size,
* and that each key maps to the same set of values in both maps.
*
* @param a a multi-map to compare
* @param b another multi-map to compare
* @return `true` if the multi-maps are equal, `false` otherwise
*
* @since UNRELEASED
*/
public static bool multi_map_str_str_equal (
MultiMap<string, string> a,
MultiMap<string, string> b)
......
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