[folks] Add missing documentation

[Travis Reitter <treitter src gnome org>]

commit d282f243ea83cb5a1ca1553076ede66649c972f3
Author: Philip Withnall <philip withnall collabora co uk>
Date:   Wed Sep 15 12:19:55 2010 +0100

    Add missing documentation

 folks/individual-aggregator.vala |   35 ++++++++++++++++++++++++++++++++++-
 folks/individual.vala            |    2 ++
 folks/persona.vala               |    6 ++++++
 folks/presence.vala              |    2 ++
 4 files changed, 44 insertions(+), 1 deletions(-)
---
diff --git a/folks/individual-aggregator.vala b/folks/individual-aggregator.vala
index d9b30bb..66bbc49 100644
--- a/folks/individual-aggregator.vala
+++ b/folks/individual-aggregator.vala
@@ -665,10 +665,24 @@ public class Folks.IndividualAggregator : Object
       yield persona.store.remove_persona (persona);
     }
 
-  /* FIXME: This should be GLib.List<Persona>, but Vala won't allow it */
+  /**
+   * Link the given { link Persona}s together.
+   *
+   * Create links between the given { link Persona}s so that they form a single
+   * { link Individual}. The new { link Individual} will be returned via the
+   * { link IndividualAggregator.individuals_changed} signal.
+   *
+   * Removal of the { link Individual}s which the { link Persona}s were in
+   * before is signalled by { link IndividualAggregator.individuals_changed} and
+   * { link Individual.removed}.
+   *
+   * @param _personas the { link Persona}s to be linked
+   * @since 0.1.13
+   */
   public async void link_personas (void *_personas)
       throws IndividualAggregatorError
     {
+      /* FIXME: _personas should be GLib.List<Persona>, but Vala won't allow it */
       unowned GLib.List<Persona> personas = (GLib.List<Persona>) _personas;
 
       if (this.writeable_store == null)
@@ -754,6 +768,25 @@ public class Folks.IndividualAggregator : Object
           this.writeable_store.id, details);
     }
 
+  /**
+   * Unlinks the given { link Individual} into its constituent { link Persona}s.
+   *
+   * This completely unlinks the given { link Individual}, destroying all of
+   * its writeable { link Persona}s.
+   *
+   * The { link Individual}'s removal is signalled by
+   * { link IndividualAggregator.individuals_changed} and
+   * { link Individual.removed}.
+   *
+   * The { link Persona}s comprising the { link Individual} will be re-linked
+   * into one or more new { link Individual}s, depending on how much linking
+   * data remains (typically only implicit links remain). The addition of these
+   * new { link Individual}s will be signalled by
+   * { link IndividualAggregator.individuals_changed}.
+   *
+   * @param individual the { link Individual} to unlink
+   * @since 0.1.13
+   */
   public async void unlink_individual (Individual individual) throws GLib.Error
     {
       if (this.linking_enabled == false)
diff --git a/folks/individual.vala b/folks/individual.vala
index de7f4d4..3f5b22d 100644
--- a/folks/individual.vala
+++ b/folks/individual.vala
@@ -320,6 +320,8 @@ public class Folks.Individual : Object,
    * `personas`. Otherwise, it will have to have personas added using the
    * { link Folks.Individual.personas} property after construction.
    *
+   * @param personas a list of { link Persona}s to initialise the
+   * { link Individual} with, or `null`
    * @return a new Individual
    */
   public Individual (GLib.List<Persona>? personas)
diff --git a/folks/persona.vala b/folks/persona.vala
index bcce582..60038cc 100644
--- a/folks/persona.vala
+++ b/folks/persona.vala
@@ -115,6 +115,8 @@ public abstract class Folks.Persona : Object
    * linkable-property-to-individual mapping it wants to add or remove in the
    * aggregator.
    *
+   * @param link the mapping string to be added to the
+   * { link IndividualAggregator}
    * @since 0.1.13
    */
   public delegate void LinkablePropertyCallback (string link);
@@ -132,6 +134,10 @@ public abstract class Folks.Persona : Object
    * added to the { link IndividualAggregator}'s link map, related to the
    * { link Individual} instance which contains this { link Persona}.
    *
+   * @param prop_name the name of the linkable property to use, which must be
+   * listed in { link Persona.linkable_properties}
+   * @param callback a callback to execute for each of the mapping strings
+   * generated by this property
    * @see Persona.linkable_properties
    * @since 0.1.13
    */
diff --git a/folks/presence.vala b/folks/presence.vala
index 6f011da..1582257 100644
--- a/folks/presence.vala
+++ b/folks/presence.vala
@@ -106,6 +106,8 @@ public interface Folks.Presence : Object
    * returned if `type_a` is more available than `type_b`, and a negative
    * number will be returned if the opposite is true.
    *
+   * @param type_a the first { link PresenceType} to compare
+   * @param type_b the second { link PresenceType} to compare
    * @return a number representing the similarity of the two types
    * @since 0.1.11
    */