GNOME.org
 

[folks] docs: Various small fixes and expansions of documentation

commit e7b96a7b2b9d3c35cf7e804018f8757f48ad2718
Author: Philip Withnall <philip tecnocode co uk>
Date:   Fri Aug 10 00:15:40 2012 +0100

    docs: Various small fixes and expansions of documentation
    
     â Various links fixed to point to class documentation rather than its
       constructor documentation (this is a quirk of Valadoc; if using
       â{ link ClassName}â inside a method of ClassName, the link will point to
       ClassNameâs constructor because symbols are resolved relatively and the
       classâ constructor is called âClassNameâ).
     â Various bits of documentation expanded (mostly trivially) to shut gtk-doc
       up about missing long descriptions.
     â Some Vala code attributes moved around so the documentation comments are
       correctly associated with the code. (This shouldnât change the behaviour
       of the attributes themselves.)
     â Some trivial constructors added to classes in order to give them
       documentation.
     â Constructor for Utils added and deprecated immediately. Utils should
       become a nested namespace on the next API break, since it will only ever
       contain static methods, and thus doesnât need to be instantiable (which
       folks will make it at the moment).

 backends/eds/lib/edsf-persona-store.vala         |    6 +++-
 backends/eds/lib/edsf-persona.vala               |    7 +++++-
 backends/libsocialweb/lib/swf-persona-store.vala |    1 +
 backends/libsocialweb/lib/swf-persona.vala       |    3 ++
 backends/telepathy/lib/tpf-persona.vala          |    6 +++++
 folks/alias-details.vala                         |    8 +++++-
 folks/avatar-cache.vala                          |   20 ++++++++++++++----
 folks/avatar-details.vala                        |   14 ++++++++----
 folks/birthday-details.vala                      |    9 +++++--
 folks/debug.vala                                 |   17 ++++++++-------
 folks/favourite-details.vala                     |    9 ++++++-
 folks/gender-details.vala                        |    4 ++-
 folks/group-details.vala                         |    8 +++++-
 folks/individual.vala                            |   14 ++++++------
 folks/interaction-details.vala                   |    9 ++++---
 folks/name-details.vala                          |    6 +++-
 folks/postal-address-details.vala                |    3 +-
 folks/potential-match.vala                       |   23 ++++++++++++++++++++-
 folks/role-details.vala                          |    6 +++-
 folks/utils.vala                                 |   23 ++++++++++++++++++++++
 20 files changed, 147 insertions(+), 49 deletions(-)
---
diff --git a/backends/eds/lib/edsf-persona-store.vala b/backends/eds/lib/edsf-persona-store.vala
index 2b727db..03e0009 100644
--- a/backends/eds/lib/edsf-persona-store.vala
+++ b/backends/eds/lib/edsf-persona-store.vala
@@ -34,8 +34,10 @@ extern const string BACKEND_NAME;
 internal extern static async E.SourceRegistry create_source_registry (GLib.Cancellable? cancellable = null) throws GLib.Error;
 
 /**
- * A persona store.
- * It will create { link Persona}s for each contacts on the main addressbook.
+ * A persona store representing a single EDS address book.
+ *
+ * The persona store will contain { link Edsf.Persona}s for each contact in the
+ * address book it represents.
  */
 public class Edsf.PersonaStore : Folks.PersonaStore
 {
diff --git a/backends/eds/lib/edsf-persona.vala b/backends/eds/lib/edsf-persona.vala
index 1310256..39c46a8 100644
--- a/backends/eds/lib/edsf-persona.vala
+++ b/backends/eds/lib/edsf-persona.vala
@@ -28,6 +28,11 @@ using Xml;
 
 /**
  * A persona subclass which represents a single EDS contact.
+ *
+ * Each { link Edsf.Persona} instance represents a single EDS { link E.Contact}.
+ * When the contact is modified (either by this folks client, or a different
+ * client), the { link Edsf.Persona} remains the same, but is assigned a new
+ * { link E.Contact}. It then updates its properties from this new contact.
  */
 public class Edsf.Persona : Folks.Persona,
     AntiLinkable,
@@ -75,12 +80,12 @@ public class Edsf.Persona : Folks.Persona,
     "email_1", "email_2", "email_3", "email_4"
   };
 
-  [Deprecated]
   /**
    * vCard field names for miscellaneous URIs.
    *
    * @since 0.6.0
    */
+  [Deprecated]
   public static const string[] url_properties = {
     "blog_url", "fburl", "homepage_url", "video_url"
   };
diff --git a/backends/libsocialweb/lib/swf-persona-store.vala b/backends/libsocialweb/lib/swf-persona-store.vala
index 4772237..72a3e44 100644
--- a/backends/libsocialweb/lib/swf-persona-store.vala
+++ b/backends/libsocialweb/lib/swf-persona-store.vala
@@ -29,6 +29,7 @@ extern const string BACKEND_NAME;
 
 /**
  * A persona store which is associated with a single libsocialweb service.
+ *
  * It will create { link Persona}s for each of the contacts known to that
  * service.
  */
diff --git a/backends/libsocialweb/lib/swf-persona.vala b/backends/libsocialweb/lib/swf-persona.vala
index cce3616..a8d9cb3 100644
--- a/backends/libsocialweb/lib/swf-persona.vala
+++ b/backends/libsocialweb/lib/swf-persona.vala
@@ -26,6 +26,9 @@ using SocialWebClient;
 
 /**
  * A persona subclass which represents a single libsocialweb contact.
+ *
+ * There is a one-to-one correspondence between { link Swf.Persona}s and
+ * { link SocialWebClient.Contact}s.
  */
 public class Swf.Persona : Folks.Persona,
     AvatarDetails,
diff --git a/backends/telepathy/lib/tpf-persona.vala b/backends/telepathy/lib/tpf-persona.vala
index 360263c..234fdbe 100644
--- a/backends/telepathy/lib/tpf-persona.vala
+++ b/backends/telepathy/lib/tpf-persona.vala
@@ -27,6 +27,12 @@ using Zeitgeist;
 /**
  * A persona subclass which represents a single instant messaging contact from
  * Telepathy.
+ *
+ * There is a one-to-one correspondence between { link Tpf.Persona}s and
+ * { link TelepathyGLib.Contact}s, although at any time the
+ * { link Tpf.Persona.contact} property of a persona may be `null` if the
+ * contact's Telepathy connection isn't available (e.g. due to being offline).
+ * In this case, the persona's properties persist from a local cache.
  */
 public class Tpf.Persona : Folks.Persona,
     AliasDetails,
diff --git a/folks/alias-details.vala b/folks/alias-details.vala
index d9b7070..953c902 100644
--- a/folks/alias-details.vala
+++ b/folks/alias-details.vala
@@ -23,8 +23,12 @@
 using GLib;
 
 /**
- * Interface for classes which represent aliasable contacts, such as
- * { link Persona} and { link Individual}.
+ * Alias for a contact.
+ *
+ * This allows representation of aliases for contacts, where the user has chosen
+ * their own name for the contact to better represent that contact to them. A
+ * typical example of this is the use of user-chosen aliases for contacts in
+ * instant messaging programs.
  */
 public interface Folks.AliasDetails : Object
 {
diff --git a/folks/avatar-cache.vala b/folks/avatar-cache.vala
index d03b74a..579d13c 100644
--- a/folks/avatar-cache.vala
+++ b/folks/avatar-cache.vala
@@ -21,9 +21,19 @@
 using GLib;
 
 /**
- * A singleton persistent cache object for avatars used across backends in
- * folks. Avatars may be added to the cache, and referred to by a persistent
- * URI from that point onwards.
+ * A singleton persistent cache for avatars in folks.
+ *
+ * Avatars may be added to the cache, and referred to by a persistent
+ * URI from that point onwards. The avatars will be stored on disk in the user's
+ * XDG cache directory.
+ *
+ * The avatar cache is typically used by backends where retrieving avatars is an
+ * expensive operation (for example, they have to be downloaded from the network
+ * every time they're used).
+ *
+ * All avatars from all users of the { link Folks.AvatarCache} are stored in the
+ * same namespace, so callers must ensure that the IDs they use for avatars are
+ * globally unique (e.g. by using the corresponding { link Folks.Persona.uid}).
  *
  * @since 0.6.0
  */
@@ -52,12 +62,12 @@ public class Folks.AvatarCache : Object
     }
 
   /**
-   * Create or return the singleton { link AvatarCache} class instance.
+   * Create or return the singleton { link Folks.AvatarCache} class instance.
    * If the instance doesn't exist already, it will be created.
    *
    * This function is thread-safe.
    *
-   * @return Singleton { link AvatarCache} instance
+   * @return Singleton { link Folks.AvatarCache} instance
    * @since 0.6.0
    */
   public static AvatarCache dup ()
diff --git a/folks/avatar-details.vala b/folks/avatar-details.vala
index 01b632f..aac38b2 100644
--- a/folks/avatar-details.vala
+++ b/folks/avatar-details.vala
@@ -23,17 +23,21 @@
 using GLib;
 
 /**
- * Interface for classes which represent contacts which have an avatar
- * (pictorial representation), such as { link Persona} and { link Individual}.
+ * Avatar for a contact.
+ *
+ * This allows avatars to be associated with contacts. An avatar is a small
+ * image file which represents the contact, such as a photo of them.
+ *
+ * @since 0.6.0
  */
 public interface Folks.AvatarDetails : Object
 {
   /**
    * An avatar for the contact.
    *
-   * 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 GLib.LoadableIcon} implementation.
+   * The avatar may be `null` if unset. Otherwise, the image data may be
+   * asynchronously loaded using the methods of the { link GLib.LoadableIcon}
+   * implementation.
    *
    * @since 0.6.0
    */
diff --git a/folks/birthday-details.vala b/folks/birthday-details.vala
index 1a16d56..7c85d00 100644
--- a/folks/birthday-details.vala
+++ b/folks/birthday-details.vala
@@ -23,8 +23,10 @@
 using GLib;
 
 /**
- * This interface contains the birth date of a { link Persona} and
- * { link Individual}
+ * Birthday details for a contact.
+ *
+ * This allows representation of the birth date and associated calendar event ID
+ * of a contact.
  *
  * @since 0.4.0
  */
@@ -63,7 +65,8 @@ public interface Folks.BirthdayDetails : Object
   /**
    * The event ID of the birthday event from the source calendar.
    *
-   * If this is `null`, the birthday event is unknown.
+   * If this is `null`, the birthday event is unknown. The semantics of the
+   * event ID are left unspecified by folks.
    *
    * @since 0.4.0
    */
diff --git a/folks/debug.vala b/folks/debug.vala
index 233af2f..7f6d98b 100644
--- a/folks/debug.vala
+++ b/folks/debug.vala
@@ -32,9 +32,10 @@ private extern void g_log (string? log_domain,
     ...);
 
 /**
- * Manage debug output and status reporting for all folks objects. All GLib
- * debug logging calls are passed through a log handler in this class, which
- * allows debug domains to be outputted according to whether they've been
+ * Manages debug output and status reporting for all folks objects.
+ *
+ * All GLib debug logging calls are passed through a log handler in this class,
+ * which allows debug domains to be outputted according to whether they've been
  * enabled by being passed to { link Debug.dup}.
  *
  * @since 0.5.1
@@ -184,13 +185,13 @@ public class Folks.Debug : Object
     }
 
   /**
-   * Create or return the singleton { link Debug} class instance.
+   * Create or return the singleton { link Folks.Debug} class instance.
    * If the instance doesn't exist already, it will be created with no debug
    * domains enabled.
    *
    * This function is thread-safe.
    *
-   * @return  Singleton { link Debug} instance
+   * @return  Singleton { link Folks.Debug} instance
    * @since 0.5.1
    */
   public static Debug dup ()
@@ -216,7 +217,7 @@ public class Folks.Debug : Object
     }
 
   /**
-   * Create or return the singleton { link Debug} class instance.
+   * Create or return the singleton { link Folks.Debug} class instance.
    * If the instance doesn't exist already, it will be created with the given
    * set of debug domains enabled. Otherwise, the existing instance will have
    * its set of enabled domains changed to the provided set.
@@ -225,7 +226,7 @@ public class Folks.Debug : Object
    * null to disable debug output
    * @param colour_enabled Whether debug output should be coloured using
    * terminal escape sequences
-   * @return Singleton { link Debug} instance
+   * @return Singleton { link Folks.Debug} instance
    * @since 0.5.1
    */
   public static Debug dup_with_flags (string? debug_flags,
@@ -315,7 +316,7 @@ public class Folks.Debug : Object
   /**
    * Causes all significant objects in the library to print their current
    * status to standard output, obeying the options set on this
-   * { link Debug} instance for colouring and other formatting.
+   * { link Folks.Debug} instance for colouring and other formatting.
    *
    * @since 0.5.1
    */
diff --git a/folks/favourite-details.vala b/folks/favourite-details.vala
index 711b97b..361187a 100644
--- a/folks/favourite-details.vala
+++ b/folks/favourite-details.vala
@@ -22,8 +22,13 @@
 using GLib;
 
 /**
- * Interface exposing a { link Persona}'s or { link Individual}'s user-defined
- * status as a favourite.
+ * Favourite status for a contact.
+ *
+ * This allows user-defined favourite contacts to be specified. A contact is a
+ * favourite if the user has selected them as such; the semantics of 'favourite'
+ * are left unspecified by folks. Typically, a user might select the contacts
+ * that they talk to most frequently as their favourite contacts in an instant
+ * messaging program, for example.
  */
 public interface Folks.FavouriteDetails : Object
 {
diff --git a/folks/gender-details.vala b/folks/gender-details.vala
index 0877de8..50f0d0d 100644
--- a/folks/gender-details.vala
+++ b/folks/gender-details.vala
@@ -45,7 +45,9 @@ public enum Folks.Gender
 }
 
 /**
- * Interface for specifying the gender of a contact.
+ * Gender of a contact.
+ *
+ * This allows representation of the gender of a contact.
  *
  * @since 0.3.5
  */
diff --git a/folks/group-details.vala b/folks/group-details.vala
index 34e58e9..95a83fe 100644
--- a/folks/group-details.vala
+++ b/folks/group-details.vala
@@ -22,8 +22,12 @@ using GLib;
 using Gee;
 
 /**
- * Interface for { link Persona}s or { link Individual}s which can be grouped
- * into sets of similar objects.
+ * Groups for a contact.
+ *
+ * This allows contacts to be collected into user-defined groups (or categories)
+ * for organisational purposes. Groups are non-exclusive and non-hierarchical,
+ * so a single contact can be put into many groups, but groups may not
+ * themselves be put into groups.
  */
 public interface Folks.GroupDetails : Object
 {
diff --git a/folks/individual.vala b/folks/individual.vala
index da02f8b..e6e3890 100644
--- a/folks/individual.vala
+++ b/folks/individual.vala
@@ -73,12 +73,12 @@ public enum Folks.TrustLevel
  * persona store (see { link IndividualAggregator.primary_store}), its property
  * values will be chosen above all others. This means that any changes to
  * property values made through folks (which are normally written to the primary
- * store) will always be used by { link Individual}s.
+ * store) will always be used by { link Folks.Individual}s.
  *
  * No further guarantees are made about the order of preference used for
- * choosing which property values to use for the { link Individual}, other than
- * that the order may vary between properties, but is guaranteed to be stable
- * for a given property.
+ * choosing which property values to use for the { link Folks.Individual}, other
+ * than that the order may vary between properties, but is guaranteed to be
+ * stable for a given property.
  */
 public class Folks.Individual : Object,
     AliasDetails,
@@ -1083,7 +1083,7 @@ public class Folks.Individual : Object,
    * { link Folks.Individual.personas} property after construction.
    *
    * @param personas a list of { link Persona}s to initialise the
-   * { link Individual} with, or `null`
+   * { link Folks.Individual} with, or `null`
    * @return a new Individual
    *
    * @since 0.5.1
@@ -2249,8 +2249,8 @@ public class Folks.Individual : Object,
    * Anti-linked with an individual?
    *
    * Check whether this individual is anti-linked to any of the { link Persona}s
-   * in { link Individual} `i`. If so, `true` will be returned â `false` will be
-   * returned otherwise.
+   * in { link Folks.Individual} `i`. If so, `true` will be returned â `false`
+   * will be returned otherwise.
    *
    * Note that this will check for anti-links in either direction, since
    * anti-links are not necessarily symmetric.
diff --git a/folks/interaction-details.vala b/folks/interaction-details.vala
index 1528f68..23c98a3 100644
--- a/folks/interaction-details.vala
+++ b/folks/interaction-details.vala
@@ -21,10 +21,11 @@
 using GLib;
 
 /**
- * Object representing interaction details for an Individual or Persona.
- * Interaction details are the number of calls or IM interactions with
- * a { link Persona} or an { link Individual} as well as the the datetime of
- * the last call and IM interaction.
+ * Interaction details of a contact.
+ *
+ * Interaction details are the number and date/time of calls or IM interactions
+ * with a contact, giving an idea of the recent interactions the user has had
+ * with that contact.
  *
  * @since 0.7.1
  */
diff --git a/folks/name-details.vala b/folks/name-details.vala
index dd35c59..22217cd 100644
--- a/folks/name-details.vala
+++ b/folks/name-details.vala
@@ -24,9 +24,11 @@
 using GLib;
 
 /**
- * Object for a full name split in its constituent parts (given name,
+ * Structured name representation for human names.
+ *
+ * Represents a full name split in its constituent parts (given name,
  * family name, etc.). This structure corresponds to the "N" field in
- * VCards.  The parts of the name are never null, an empty string
+ * vCards. The parts of the name are never `null`: an empty string
  * indicates that a property is not set.
  *
  * @since 0.3.5
diff --git a/folks/postal-address-details.vala b/folks/postal-address-details.vala
index a2a1490..6695450 100644
--- a/folks/postal-address-details.vala
+++ b/folks/postal-address-details.vala
@@ -26,7 +26,8 @@ using Gee;
 
 /**
  * Object representing a postal mail address.
- * The components of the address are never null, an empty string
+ *
+ * The components of the address are never `null`: an empty string
  * indicates that a property is not set.
  */
 public class Folks.PostalAddress : Object
diff --git a/folks/potential-match.vala b/folks/potential-match.vala
index 49fe4d1..aa58df9 100644
--- a/folks/potential-match.vala
+++ b/folks/potential-match.vala
@@ -78,8 +78,15 @@ public enum Folks.MatchResult
 }
 
 /**
- * This class provides functionality to explore a potential match between
- * two individuals.
+ * Match calculator for pairs of individuals.
+ *
+ * This provides functionality to explore the degree of a potential match
+ * between two individuals. It compares the similarity of the individuals'
+ * properties to determine how likely it is that the individuals represent the
+ * same physical person.
+ *
+ * This can be used by folks clients to, for example, present suggestions of
+ * pairs of individuals which should be linked by the user.
  *
  * @since 0.5.0
  */
@@ -108,6 +115,18 @@ public class Folks.PotentialMatch : Object
     }
 
   /**
+   * Create a new PotentialMatch.
+   *
+   * @return a new PotentialMatch
+   *
+   * @since 0.5.0
+   */
+  public PotentialMatch ()
+    {
+      base ();
+    }
+
+  /**
    * Whether two individuals are likely to be the same person.
    *
    * @param a an individual to compare
diff --git a/folks/role-details.vala b/folks/role-details.vala
index d6aa410..9237b92 100644
--- a/folks/role-details.vala
+++ b/folks/role-details.vala
@@ -25,8 +25,10 @@ using Gee;
 using GLib;
 
 /**
- * This interface represents the role a { link Persona} and { link Individual}
- * have in a given Organisation.
+ * Role a contact has in an organisation.
+ *
+ * This represents the role a { link Persona} or { link Individual} has in a
+ * single given organisation, such as a company.
  *
  * @since 0.4.0
  */
diff --git a/folks/utils.vala b/folks/utils.vala
index 70e738c..afa5f0b 100644
--- a/folks/utils.vala
+++ b/folks/utils.vala
@@ -21,9 +21,17 @@
 
 using Gee;
 
+/* TODO: This should be converted to a nested namespace, rather than a class,
+ * when folks next breaks API. Having it as a class means that a GType is always
+ * registered for it, and a C constructor function created, even though
+ * instantiating it is pointless as all the methods are static (and should
+ * remain so). */
 /**
  * Utility functions to simplify common patterns in Folks client code.
  *
+ * These may be used by folks clients as well, and are part of folks' supported
+ * stable API.
+ *
  * @since 0.6.0
  */
 public class Folks.Utils : Object
@@ -34,6 +42,21 @@ public class Folks.Utils : Object
     }
 
   /**
+   * Create a new utilities object.
+   *
+   * This method is useless and should never be used. It will be removed in a
+   * future version in favour of making the Utils class into a nested namespace.
+   *
+   * @return a new utilities object
+   * @since 0.6.0
+   */
+  [Deprecated (since = "UNRELEASED")]
+  public Utils ()
+    {
+      base ();
+    }
+
+  /**
    * 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.
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]