GNOME.org
 

[folks] docs: Various documentation fixes

commit 1cf34ed63c050935241271c9ec7838086b2ef0eb
Author: Philip Withnall <philip tecnocode co uk>
Date:   Mon Mar 26 19:20:03 2012 +0100

    docs: Various documentation fixes

 backends/eds/lib/edsf-persona.vala               |   23 ++++++++++++++++++++++
 backends/libsocialweb/lib/swf-persona-store.vala |    3 ++
 backends/libsocialweb/lib/swf-persona.vala       |   22 +++++++++++++++++++++
 backends/telepathy/lib/tpf-persona-store.vala    |   16 +++++++-------
 folks/email-details.vala                         |    2 +-
 folks/note-details.vala                          |    2 +
 folks/persona-store.vala                         |    4 +-
 folks/postal-address-details.vala                |    1 -
 8 files changed, 61 insertions(+), 12 deletions(-)
---
diff --git a/backends/eds/lib/edsf-persona.vala b/backends/eds/lib/edsf-persona.vala
index 5e6d935..bef9a63 100644
--- a/backends/eds/lib/edsf-persona.vala
+++ b/backends/eds/lib/edsf-persona.vala
@@ -47,19 +47,39 @@ public class Edsf.Persona : Folks.Persona,
     WebServiceDetails
 {
   /* The following 4 definitions are used by the tests */
+  /**
+   * vCard field names for telephone numbers.
+   *
+   * @since 0.6.0
+   */
   public static const string[] phone_fields = {
     "assistant_phone", "business_phone", "business_phone_2", "callback_phone",
     "car_phone", "company_phone", "home_phone", "home_phone_2", "isdn_phone",
     "mobile_phone", "other_phone", "primary_phone"
   };
+  /**
+   * vCard field names for postal addresses.
+   *
+   * @since 0.6.0
+   */
   public static const string[] address_fields = {
     "address_home", "address_other", "address_work"
   };
+  /**
+   * vCard field names for e-mail addresses.
+   *
+   * @since 0.6.0
+   */
   public static const string[] email_fields = {
     "email_1", "email_2", "email_3", "email_4"
   };
 
   [Deprecated]
+  /**
+   * vCard field names for miscellaneous URIs.
+   *
+   * @since 0.6.0
+   */
   public static const string[] url_properties = {
     "blog_url", "fburl", "homepage_url", "video_url"
   };
@@ -690,6 +710,9 @@ public class Edsf.Persona : Folks.Persona,
    * Create a new persona for the { link PersonaStore} `store`, representing
    * the EDS contact given by `contact`.
    *
+   * @param store the store which will contain the persona
+   * @param contact the EDS contact being represented by the persona
+   *
    * @since 0.6.0
    */
   public Persona (PersonaStore store, E.Contact contact)
diff --git a/backends/libsocialweb/lib/swf-persona-store.vala b/backends/libsocialweb/lib/swf-persona-store.vala
index 8a00403..6bb4b1d 100644
--- a/backends/libsocialweb/lib/swf-persona-store.vala
+++ b/backends/libsocialweb/lib/swf-persona-store.vala
@@ -161,6 +161,9 @@ public class Swf.PersonaStore : Folks.PersonaStore
    *
    * Create a new persona store to store the { link Persona}s for the contacts
    * provided by the `service`.
+   *
+   * @param service the libsocialweb service being represented by the new
+   * persona store
    */
   public PersonaStore (ClientService service)
     {
diff --git a/backends/libsocialweb/lib/swf-persona.vala b/backends/libsocialweb/lib/swf-persona.vala
index f4fedce..cce3616 100644
--- a/backends/libsocialweb/lib/swf-persona.vala
+++ b/backends/libsocialweb/lib/swf-persona.vala
@@ -249,6 +249,10 @@ public class Swf.Persona : Folks.Persona,
    *
    * Create a new persona for the { link PersonaStore} `store`, representing
    * the libsocialweb contact given by `contact`.
+   *
+   * @param store the store which will contain the persona
+   * @param contact the libsocialweb contact being represented by the new
+   * persona
    */
   public Persona (PersonaStore store, Contact contact)
     {
@@ -303,11 +307,29 @@ public class Swf.Persona : Folks.Persona,
       this._lsw_contact = null;
     }
 
+  /**
+   * Get the ID of the libsocialweb contact.
+   *
+   * @param contact contact to return the ID from
+   * @return ID of `contact`
+   *
+   * @since 0.5.0
+   */
   public static string? get_contact_id (Contact contact)
     {
       return contact.get_value ("id");
     }
 
+  /**
+   * Update the persona from the given contact.
+   *
+   * This will update the values of all the persona's properties from the
+   * properties of the given contact.
+   *
+   * @param contact contact to update the persona from
+   *
+   * @since 0.5.0
+   */
   public void update (Contact contact)
     {
       var nickname = contact.get_value ("name");
diff --git a/backends/telepathy/lib/tpf-persona-store.vala b/backends/telepathy/lib/tpf-persona-store.vala
index aec05b8..946cc76 100644
--- a/backends/telepathy/lib/tpf-persona-store.vala
+++ b/backends/telepathy/lib/tpf-persona-store.vala
@@ -2559,16 +2559,16 @@ public class Tpf.PersonaStore : Folks.PersonaStore
   /**
    * Get a map of all the currently constructed { link Tpf.PersonaStore}s.
    *
-   * If a { link BackendStore} has been prepared, this map will be complete,
-   * containing every store known to the Telepathy account manager. If no
-   * { link BackendStore} has been prepared, this map will only contain the
-   * stores which have been created by calling
+   * If a { link Folks.BackendStore} has been prepared, this map will be
+   * complete, containing every store known to the Telepathy account manager. If
+   * no { link Folks.BackendStore} has been prepared, this map will only contain
+   * the stores which have been created by calling
    * { link Tpf.PersonaStore.dup_for_account}.
    *
-   * This map is read-only. Use { link BackendStore} or
+   * This map is read-only. Use { link Folks.BackendStore} or
    * { link Tpf.PersonaStore.dup_for_account} to add stores.
    *
-   * @return map from { link PersonaStore.id} to { link PersonaStore}
+   * @return map from { link Folks.PersonaStore.id} to { link Tpf.PersonaStore}
    * @since 0.6.6
    */
   public static unowned Map<string, PersonaStore> list_persona_stores ()
@@ -2654,8 +2654,8 @@ public class Tpf.PersonaStore : Folks.PersonaStore
    * found, a new { link Tpf.PersonaStore} will be created for the account.
    *
    * See the documentation for { link Tpf.PersonaStore.list_persona_stores} for
-   * information on the lifecycle of these stores when a { link BackendStore} is
-   * and is not present.
+   * information on the lifecycle of these stores when a
+   * { link Folks.BackendStore} is and is not present.
    *
    * @param account the Telepathy account of the persona store
    * @return the persona store associated with the account
diff --git a/folks/email-details.vala b/folks/email-details.vala
index 141025c..e8ea513 100644
--- a/folks/email-details.vala
+++ b/folks/email-details.vala
@@ -94,7 +94,7 @@ public interface Folks.EmailDetails : Object
    *
    * Each of the values in this property contains just an e-mail address (e.g.
    * âfoo bar comâ), rather than any other way of formatting an e-mail address
-   * (such as âJohn Smith <foo bar com>â).
+   * (such as âJohn Smith &lt;foo bar com&gt;â).
    *
    * @since 0.6.0
    */
diff --git a/folks/note-details.vala b/folks/note-details.vala
index 392e1c9..f7624df 100644
--- a/folks/note-details.vala
+++ b/folks/note-details.vala
@@ -61,6 +61,8 @@ public class Folks.NoteFieldDetails : AbstractFieldDetails<string>
    * @param parameters initial parameters. See
    * { link AbstractFieldDetails.parameters}. A `null` value is equivalent to a
    * empty map of parameters.
+   * @param uid UID for the note object itself, if known. A `null` value means
+   * the note has no unique ID.
    *
    * @return a new NoteFieldDetails
    *
diff --git a/folks/persona-store.vala b/folks/persona-store.vala
index c885a83..06d14c4 100644
--- a/folks/persona-store.vala
+++ b/folks/persona-store.vala
@@ -629,7 +629,7 @@ public abstract class Folks.PersonaStore : Object
    * return value is purely for convenience, since it can be complicated to
    * correlate the provided details with the final Persona.
    *
-   * If the store is offline (or { link PersonaStore.prepare()} hasn't yet been
+   * If the store is offline (or { link PersonaStore.prepare} hasn't yet been
    * called successfully), this function will throw
    * { link PersonaStoreError.STORE_OFFLINE}. It's the responsibility of the
    * caller to cache details and re-try this function if it wishes to make
@@ -662,7 +662,7 @@ public abstract class Folks.PersonaStore : Object
    * will be signalled through emission of
    * { link PersonaStore.personas_changed}.
    *
-   * If the store is offline (or { link PersonaStore.prepare()} hasn't yet been
+   * If the store is offline (or { link PersonaStore.prepare} hasn't yet been
    * called successfully), this function will throw
    * { link PersonaStoreError.STORE_OFFLINE}. It's the responsibility of the
    * caller to cache details and re-try this function if it wishes to make
diff --git a/folks/postal-address-details.vala b/folks/postal-address-details.vala
index b13e001..a2a1490 100644
--- a/folks/postal-address-details.vala
+++ b/folks/postal-address-details.vala
@@ -154,7 +154,6 @@ public class Folks.PostalAddress : Object
    * @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
    */
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]