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

From: Philip Withnall <pwithnall src gnome org>
To: commits-list gnome org
Cc:
Subject: [folks] docs: Fix up lots of minor issues in the documentation comments
Date: Fri, 29 Jul 2011 19:46:01 +0000 (UTC)
commit c93131b6d4d9226dd4d78c2ba58548a8e5c315f0
Author: Philip Withnall <philip tecnocode co uk>
Date:   Fri Jul 29 20:06:55 2011 +0100

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

 backends/eds/lib/memory-icon.vala |    4 +-
 folks/avatar-cache.vala           |    4 +-
 folks/avatar-details.vala         |    2 +-
 folks/individual-aggregator.vala  |   12 ++++
 folks/individual.vala             |    4 +-
 folks/name-details.vala           |    1 +
 folks/note-details.vala           |    9 +++-
 folks/object-cache.vala           |   22 +++++---
 folks/persona-store.vala          |  105 ++++++++++++++++++++++++++++++++++++-
 folks/phone-details.vala          |   19 +++++--
 folks/postal-address-details.vala |   16 +++++-
 folks/potential-match.vala        |   32 +++++++++++
 folks/role-details.vala           |   12 ++++-
 folks/utils.vala                  |   11 ++++
 14 files changed, 228 insertions(+), 25 deletions(-)
---
diff --git a/backends/eds/lib/memory-icon.vala b/backends/eds/lib/memory-icon.vala
index 16dab82..8e6fb20 100644
--- a/backends/eds/lib/memory-icon.vala
+++ b/backends/eds/lib/memory-icon.vala
@@ -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
  */
diff --git a/folks/avatar-cache.vala b/folks/avatar-cache.vala
index 8c0f4de..32a854c 100644
--- a/folks/avatar-cache.vala
+++ b/folks/avatar-cache.vala
@@ -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
diff --git a/folks/avatar-details.vala b/folks/avatar-details.vala
index 135cfee..4e3337c 100644
--- a/folks/avatar-details.vala
+++ b/folks/avatar-details.vala
@@ -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
    */
diff --git a/folks/individual-aggregator.vala b/folks/individual-aggregator.vala
index 3b7bc86..049e722 100644
--- a/folks/individual-aggregator.vala
+++ b/folks/individual-aggregator.vala
@@ -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>>
diff --git a/folks/individual.vala b/folks/individual.vala
index bf4897d..53db48d 100644
--- a/folks/individual.vala
+++ b/folks/individual.vala
@@ -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
diff --git a/folks/name-details.vala b/folks/name-details.vala
index d4779b8..34c9df9 100644
--- a/folks/name-details.vala
+++ b/folks/name-details.vala
@@ -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.
    *
diff --git a/folks/note-details.vala b/folks/note-details.vala
index bafcaaa..4306cdc 100644
--- a/folks/note-details.vala
+++ b/folks/note-details.vala
@@ -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)
     {
diff --git a/folks/object-cache.vala b/folks/object-cache.vala
index 3724f9e..2cbe6fb 100644
--- a/folks/object-cache.vala
+++ b/folks/object-cache.vala
@@ -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
    */
diff --git a/folks/persona-store.vala b/folks/persona-store.vala
index 4922a59..e70e88a 100644
--- a/folks/persona-store.vala
+++ b/folks/persona-store.vala
@@ -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
    *
diff --git a/folks/phone-details.vala b/folks/phone-details.vala
index 0aa3fd1..5653f25 100644
--- a/folks/phone-details.vala
+++ b/folks/phone-details.vala
@@ -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
    */
diff --git a/folks/postal-address-details.vala b/folks/postal-address-details.vala
index 7b30213..ebcc065 100644
--- a/folks/postal-address-details.vala
+++ b/folks/postal-address-details.vala
@@ -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
    */
diff --git a/folks/potential-match.vala b/folks/potential-match.vala
index 17f1a4d..6716d86 100644
--- a/folks/potential-match.vala
+++ b/folks/potential-match.vala
@@ -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)
diff --git a/folks/role-details.vala b/folks/role-details.vala
index bc08d16..98b5e5e 100644
--- a/folks/role-details.vala
+++ b/folks/role-details.vala
@@ -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)
     {
diff --git a/folks/utils.vala b/folks/utils.vala
index 5f75765..0e57eb9 100644
--- a/folks/utils.vala
+++ b/folks/utils.vala
@@ -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)
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]