[folks] docs: Use correct Valadoc syntax for monospaced content
- From: Philip Withnall <pwithnall src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [folks] docs: Use correct Valadoc syntax for monospaced content
- Date: Tue, 14 Aug 2012 20:22:55 +0000 (UTC)
commit d2d8ceb2e7d586a1addb1739b2e0a612c3041a14
Author: Philip Withnall <philip tecnocode co uk>
Date: Tue Aug 14 21:21:05 2012 +0100
docs: Use correct Valadoc syntax for monospaced content
The syntax is â``monospaced text``â rather than â`monospaced text`â, which
we were consistently getting wrong. Valadoc now produces the correct markup
for monospaced text, but it doesnât appear differently from other text at
the moment due to Valadoc not having any CSS for it. That will change soon.
Similarly, Valadoc currently produces the wrong markup for monospaced text
with the gtkdoc doclet, but that will soon be fixed.
See: https://bugzilla.gnome.org/show_bug.cgi?id=681721
backends/eds/lib/edsf-persona-store.vala | 4 +-
backends/eds/lib/edsf-persona.vala | 4 +-
backends/eds/lib/memory-icon.vala | 12 ++--
backends/key-file/kf-persona-store.vala | 4 +-
backends/key-file/kf-persona.vala | 4 +-
backends/libsocialweb/lib/swf-persona-store.vala | 2 +-
backends/libsocialweb/lib/swf-persona.vala | 6 +-
.../telepathy/lib/tpf-persona-store-cache.vala | 24 ++++----
backends/telepathy/lib/tpf-persona-store.vala | 8 +-
backends/telepathy/lib/tpf-persona.vala | 28 +++++-----
backends/tracker/lib/trf-persona-store.vala | 4 +-
backends/tracker/lib/trf-persona.vala | 2 +-
folks/abstract-field-details.vala | 14 ++--
folks/alias-details.vala | 2 +-
folks/anti-linkable.vala | 10 ++--
folks/avatar-cache.vala | 2 +-
folks/avatar-details.vala | 4 +-
folks/backend-store.vala | 8 +-
folks/backend.vala | 4 +-
folks/birthday-details.vala | 9 ++-
folks/email-details.vala | 4 +-
folks/favourite-details.vala | 3 +-
folks/group-details.vala | 4 +-
folks/im-details.vala | 4 +-
folks/individual-aggregator.vala | 48 ++++++++--------
folks/individual.vala | 61 ++++++++++---------
folks/name-details.vala | 22 ++++----
folks/note-details.vala | 6 +-
folks/object-cache.vala | 35 ++++++-----
folks/persona-store.vala | 23 ++++----
folks/persona.vala | 10 ++--
folks/phone-details.vala | 12 ++--
folks/postal-address-details.vala | 14 ++--
folks/presence-details.vala | 12 ++--
folks/role-details.vala | 6 +-
folks/url-details.vala | 4 +-
folks/utils.vala | 6 +-
folks/web-service-details.vala | 4 +-
tests/lib/test-utils.vala | 4 +-
tools/inspect/inspect.vala | 4 +-
40 files changed, 225 insertions(+), 216 deletions(-)
---
diff --git a/backends/eds/lib/edsf-persona-store.vala b/backends/eds/lib/edsf-persona-store.vala
index 03e0009..05cdc17 100644
--- a/backends/eds/lib/edsf-persona-store.vala
+++ b/backends/eds/lib/edsf-persona-store.vala
@@ -244,7 +244,7 @@ public class Edsf.PersonaStore : Folks.PersonaStore
* Create a new PersonaStore.
*
* Create a new persona store to store the { link Persona}s for the contacts
- * in `s`. Passing a re-used source registry to the constructor (compared to
+ * in ``s``. Passing a re-used source registry to the constructor (compared to
* the old { link Edsf.PersonaStore} constructor) saves a lot of time and
* D-Bus round trips.
*
@@ -316,7 +316,7 @@ public class Edsf.PersonaStore : Folks.PersonaStore
/**
* Add a new { link Persona} to the PersonaStore.
*
- * Accepted keys for `details` are:
+ * Accepted keys for ``details`` are:
* - PersonaStore.detail_key (PersonaDetail.AVATAR)
* - PersonaStore.detail_key (PersonaDetail.BIRTHDAY)
* - PersonaStore.detail_key (PersonaDetail.EMAIL_ADDRESSES)
diff --git a/backends/eds/lib/edsf-persona.vala b/backends/eds/lib/edsf-persona.vala
index bfc92d0..f757f7d 100644
--- a/backends/eds/lib/edsf-persona.vala
+++ b/backends/eds/lib/edsf-persona.vala
@@ -754,8 +754,8 @@ public class Edsf.Persona : Folks.Persona,
/**
* Create a new persona.
*
- * Create a new persona for the { link PersonaStore} `store`, representing
- * the EDS contact given by `contact`.
+ * 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
diff --git a/backends/eds/lib/memory-icon.vala b/backends/eds/lib/memory-icon.vala
index aeb2d34..18a7c9a 100644
--- a/backends/eds/lib/memory-icon.vala
+++ b/backends/eds/lib/memory-icon.vala
@@ -51,10 +51,10 @@ internal class Edsf.MemoryIcon : Object, Icon, LoadableIcon
/**
* Decide whether two { link MemoryIcon} instances are equal. This compares
- * their image data and returns `true` if they are identical.
+ * their image data and returns ``true`` if they are identical.
*
* @param icon2 the { link MemoryIcon} instance to compare against
- * @return `true` if the instances are equal, `false` otherwise
+ * @return ``true`` if the instances are equal, ``false`` otherwise
* @since 0.6.0
*/
public bool equal (Icon? icon2)
@@ -102,8 +102,8 @@ internal class Edsf.MemoryIcon : Object, Icon, LoadableIcon
* without blocking on I/O.
*
* @param size the square dimensions to output the image at (unused), or -1
- * @param type return location for the content type of the image, or `null`
- * @param cancellable optional { link GLib.Cancellable}, or `null`
+ * @param type return location for the content type of the image, or ``null``
+ * @param cancellable optional { link GLib.Cancellable}, or ``null``
* @return an input stream providing access to the image data
* @since 0.6.0
*/
@@ -119,8 +119,8 @@ internal class Edsf.MemoryIcon : Object, Icon, LoadableIcon
* will complete without blocking on I/O.
*
* @param size the square dimensions to output the image at (unused), or -1
- * @param cancellable optional { link GLib.Cancellable}, or `null`
- * @param type return location for the content type of the image, or `null`
+ * @param cancellable optional { link GLib.Cancellable}, or ``null``
+ * @param type return location for the content type of the image, or ``null``
* @return an input stream providing access to the image data
* @since 0.6.0
*/
diff --git a/backends/key-file/kf-persona-store.vala b/backends/key-file/kf-persona-store.vala
index af63f14..c989ae3 100644
--- a/backends/key-file/kf-persona-store.vala
+++ b/backends/key-file/kf-persona-store.vala
@@ -158,7 +158,7 @@ public class Folks.Backends.Kf.PersonaStore : Folks.PersonaStore
* Create a new PersonaStore.
*
* Create a new persona store to expose the { link Persona}s provided by the
- * different groups in the key file given by `key_file`.
+ * different groups in the key file given by ``key_file``.
*/
public PersonaStore (File key_file)
{
@@ -360,7 +360,7 @@ public class Folks.Backends.Kf.PersonaStore : Folks.PersonaStore
/**
* Add a new { link Persona} to the PersonaStore.
*
- * Accepted keys for `details` are:
+ * Accepted keys for ``details`` are:
* - PersonaStore.detail_key (PersonaDetail.IM_ADDRESSES)
* - PersonaStore.detail_key (PersonaDetail.WEB_SERVICE_ADDRESSES)
*
diff --git a/backends/key-file/kf-persona.vala b/backends/key-file/kf-persona.vala
index 5db01db..d189d2f 100644
--- a/backends/key-file/kf-persona.vala
+++ b/backends/key-file/kf-persona.vala
@@ -306,8 +306,8 @@ public class Folks.Backends.Kf.Persona : Folks.Persona,
/**
* Create a new persona.
*
- * Create a new persona for the { link PersonaStore} `store`, representing
- * the Persona given by the group `uid` in the key file `key_file`.
+ * Create a new persona for the { link PersonaStore} ``store``, representing
+ * the Persona given by the group ``uid`` in the key file ``key_file``.
*/
public Persona (string id, Folks.PersonaStore store)
{
diff --git a/backends/libsocialweb/lib/swf-persona-store.vala b/backends/libsocialweb/lib/swf-persona-store.vala
index 72a3e44..e577867 100644
--- a/backends/libsocialweb/lib/swf-persona-store.vala
+++ b/backends/libsocialweb/lib/swf-persona-store.vala
@@ -161,7 +161,7 @@ public class Swf.PersonaStore : Folks.PersonaStore
* Create a new PersonaStore.
*
* Create a new persona store to store the { link Persona}s for the contacts
- * provided by the `service`.
+ * provided by the ``service``.
*
* @param service the libsocialweb service being represented by the new
* persona store
diff --git a/backends/libsocialweb/lib/swf-persona.vala b/backends/libsocialweb/lib/swf-persona.vala
index a8d9cb3..fd5511e 100644
--- a/backends/libsocialweb/lib/swf-persona.vala
+++ b/backends/libsocialweb/lib/swf-persona.vala
@@ -250,8 +250,8 @@ public class Swf.Persona : Folks.Persona,
/**
* Create a new persona.
*
- * Create a new persona for the { link PersonaStore} `store`, representing
- * the libsocialweb contact given by `contact`.
+ * 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
@@ -314,7 +314,7 @@ public class Swf.Persona : Folks.Persona,
* Get the ID of the libsocialweb contact.
*
* @param contact contact to return the ID from
- * @return ID of `contact`
+ * @return ID of ``contact``
*
* @since 0.5.0
*/
diff --git a/backends/telepathy/lib/tpf-persona-store-cache.vala b/backends/telepathy/lib/tpf-persona-store-cache.vala
index a6352a0..0021b2b 100644
--- a/backends/telepathy/lib/tpf-persona-store-cache.vala
+++ b/backends/telepathy/lib/tpf-persona-store-cache.vala
@@ -28,18 +28,18 @@ using Folks;
*
* Each { link Tpf.Persona} is stored as a serialised { link Variant} which is
* a tuple containing the following fields:
- * # UID (`s`)
- * # IID (`s`)
- * # IM address (`s`)
- * # Protocol (`s`)
- * # Set of group names (`as`)
- * # Favourite? (`b`)
- * # Alias (`s`)
- * # In contact list? (`b`)
- * # Avatar file URI (`s`)
- * # Birthday date as a Unix timestamp (`s`)
- * # Set of e-mail addresses and parameters (`a(sa(ss))`)
- * # Full name (`s`)
+ * # UID (``s``)
+ * # IID (``s``)
+ * # IM address (``s``)
+ * # Protocol (``s``)
+ * # Set of group names (``as``)
+ * # Favourite? (``b``)
+ * # Alias (``s``)
+ * # In contact list? (``b``)
+ * # Avatar file URI (``s``)
+ * # Birthday date as a Unix timestamp (``s``)
+ * # Set of e-mail addresses and parameters (``a(sa(ss))``)
+ * # Full name (``s``)
*
* @since 0.6.0
*/
diff --git a/backends/telepathy/lib/tpf-persona-store.vala b/backends/telepathy/lib/tpf-persona-store.vala
index f9121b3..bbff7c3 100644
--- a/backends/telepathy/lib/tpf-persona-store.vala
+++ b/backends/telepathy/lib/tpf-persona-store.vala
@@ -237,7 +237,7 @@ public class Tpf.PersonaStore : Folks.PersonaStore
* Create a new PersonaStore.
*
* Create a new persona store to store the { link Persona}s for the contacts
- * in the Telepathy account provided by `account`.
+ * in the Telepathy account provided by ``account``.
*
* @param account the Telepathy account being represented by the persona store
*/
@@ -1190,7 +1190,7 @@ public class Tpf.PersonaStore : Folks.PersonaStore
*
* See { link Folks.PersonaStore.remove_persona}.
*
- * @throws Folks.PersonaStoreError.UNSUPPORTED_ON_USER if `persona` is the
+ * @throws Folks.PersonaStoreError.UNSUPPORTED_ON_USER if ``persona`` is the
* local user â removing the local user isnât supported
* @throws Folks.PersonaStoreError.REMOVE_FAILED if removing the contact
* failed
@@ -1238,8 +1238,8 @@ public class Tpf.PersonaStore : Folks.PersonaStore
*
* See { link Folks.PersonaStore.add_persona_from_details}.
*
- * @throws Folks.PersonaStoreError.INVALID_ARGUMENT if the `contact` key was
- * not provided in `details`
+ * @throws Folks.PersonaStoreError.INVALID_ARGUMENT if the ``contact`` key was
+ * not provided in ``details``
* @throws Folks.PersonaStoreError.STORE_OFFLINE if the CM is offline
* @throws Folks.PersonaStoreError.CREATE_FAILED if adding the contact failed
*/
diff --git a/backends/telepathy/lib/tpf-persona.vala b/backends/telepathy/lib/tpf-persona.vala
index 234fdbe..e1cdaae 100644
--- a/backends/telepathy/lib/tpf-persona.vala
+++ b/backends/telepathy/lib/tpf-persona.vala
@@ -30,7 +30,7 @@ using Zeitgeist;
*
* 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
+ * { 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.
*/
@@ -573,7 +573,7 @@ public class Tpf.Persona : Folks.Persona,
/**
* The Telepathy contact represented by this persona.
*
- * Note that this may be `null` if the { link PersonaStore} providing this
+ * Note that this may be ``null`` if the { link PersonaStore} providing this
* { link Persona} isn't currently available (e.g. due to not being connected
* to the network). In this case, most other properties of the { link Persona}
* are being retrieved from a cache and may not be current (though there's no
@@ -700,8 +700,8 @@ public class Tpf.Persona : Folks.Persona,
/**
* Create a new persona.
*
- * Create a new persona for the { link PersonaStore} `store`, representing
- * the Telepathy contact given by `contact`.
+ * Create a new persona for the { link PersonaStore} ``store``, representing
+ * the Telepathy contact given by ``contact``.
*
* @param contact the Telepathy contact being represented by the persona
* @param store the persona store to place the persona in
@@ -1015,7 +1015,7 @@ public class Tpf.Persona : Folks.Persona,
}
/**
- * Create a new persona for the { link PersonaStore} `store`, representing
+ * Create a new persona for the { link PersonaStore} ``store``, representing
* a cached contact for which we currently have no Telepathy contact.
*
* @param store The persona store to place the persona in.
@@ -1030,18 +1030,18 @@ public class Tpf.Persona : Folks.Persona,
* @param is_in_contact_list Whether the persona is in the user's contact
* list.
* @param is_user Whether the persona is the user.
- * @param avatar The icon for the persona's cached avatar, or `null` if they
+ * @param avatar The icon for the persona's cached avatar, or ``null`` if they
* have no avatar.
- * @param birthday The date/time of birth of the persona, or `null` if it's
+ * @param birthday The date/time of birth of the persona, or ``null`` if it's
* unknown.
* @param full_name The persona's full name, or the empty string if it's
* unknown.
* @param email_addresses A set of the persona's e-mail addresses, which may
- * be empty (but may not be `null`).
+ * be empty (but may not be ``null``).
* @param phone_numbers A set of the persona's phone numbers, which may be
- * empty (but may not be `null`).
+ * empty (but may not be ``null``).
* @param urls A set of the persona's URLs, which may be empty (but may not be
- * `null`).
+ * ``null``).
* @return A new { link Tpf.Persona} representing the cached persona.
*
* @since 0.6.0
@@ -1221,16 +1221,16 @@ public class Tpf.Persona : Folks.Persona,
* Look up a { link Tpf.Persona} by its { link TelepathyGLib.Contact}.
*
* If the { link TelepathyGLib.Account} for the contact's
- * { link TelepathyGLib.Connection} is `null`, or if a
- * { link Tpf.PersonaStore} can't be found for that account, `null` will be
+ * { link TelepathyGLib.Connection} is ``null``, or if a
+ * { link Tpf.PersonaStore} can't be found for that account, ``null`` will be
* returned. Otherwise, if a { link Tpf.Persona} already exists for the given
* contact, that will be returned; if one doesn't exist a new one will be
* created and returned. In this case, the { link Tpf.Persona} will be added
* to the { link PersonaStore} associated with the account, and will be
- * removed when `contact` is destroyed.
+ * removed when ``contact`` is destroyed.
*
* @param contact the Telepathy contact of the persona
- * @return the persona associated with the contact, or `null`
+ * @return the persona associated with the contact, or ``null``
* @since 0.6.6
*/
public static Persona? dup_for_contact (Contact contact)
diff --git a/backends/tracker/lib/trf-persona-store.vala b/backends/tracker/lib/trf-persona-store.vala
index 07101bc..eec04e8 100644
--- a/backends/tracker/lib/trf-persona-store.vala
+++ b/backends/tracker/lib/trf-persona-store.vala
@@ -429,7 +429,7 @@ public class Trf.PersonaStore : Folks.PersonaStore
/**
* Add a new { link Persona} to the PersonaStore.
*
- * Accepted keys for `details` are:
+ * Accepted keys for ``details`` are:
* - PersonaStore.detail_key (PersonaDetail.IM_ADDRESSES)
* - PersonaStore.detail_key (PersonaDetail.NICKNAME)
* - PersonaStore.detail_key (PersonaDetail.FULL_NAME)
@@ -450,7 +450,7 @@ public class Trf.PersonaStore : Folks.PersonaStore
* See { link Folks.PersonaStore.add_persona_from_details}.
*
* @throws Folks.PersonaStoreError.INVALID_ARGUMENT if an unrecognised detail
- * key was passed in `details`
+ * key was passed in ``details``
*/
public override async Folks.Persona? add_persona_from_details (
HashTable<string, Value?> details) throws Folks.PersonaStoreError
diff --git a/backends/tracker/lib/trf-persona.vala b/backends/tracker/lib/trf-persona.vala
index 7c8f85d..bfbc466 100644
--- a/backends/tracker/lib/trf-persona.vala
+++ b/backends/tracker/lib/trf-persona.vala
@@ -511,7 +511,7 @@ public class Trf.Persona : Folks.Persona,
/**
* Create a new persona.
*
- * Create a new persona for the { link PersonaStore} `store`, representing
+ * Create a new persona for the { link PersonaStore} ``store``, representing
* the nco:Contact whose details are stored in the cursor.
*/
public Persona (PersonaStore store, string tracker_id,
diff --git a/folks/abstract-field-details.vala b/folks/abstract-field-details.vala
index 91281e4..8bd5202 100644
--- a/folks/abstract-field-details.vala
+++ b/folks/abstract-field-details.vala
@@ -29,9 +29,9 @@ using Gee;
* Some contact details, like phone numbers or URLs, can have some
* extra details associated with them.
* For instance, a phone number expressed in vcard notation as
- * `tel;type=work,voice:(111) 555-1234` would be represented as
+ * ``tel;type=work,voice:(111) 555-1234`` would be represented as
* a AbstractFieldDetails with value "(111) 555-1234" and with parameters
- * `['type': ('work', 'voice')]`.
+ * ``['type': ('work', 'voice')]``.
*
* The parameter name "type" with values "work", "home", or "other" are common
* amongst most vCard attributes (and thus most AbstractFieldDetails-derived
@@ -161,7 +161,7 @@ public abstract class Folks.AbstractFieldDetails<T> : Object
* Get the values for a parameter
*
* @param parameter_name the parameter name
- * @return a collection of values for `parameter_name` or `null` (i.e. no
+ * @return a collection of values for ``parameter_name`` or ``null`` (i.e. no
* collection) if there are no such parameters.
*
* @since 0.6.0
@@ -179,8 +179,8 @@ public abstract class Folks.AbstractFieldDetails<T> : Object
/**
* Add a new value for a parameter.
*
- * If there is already a parameter called `parameter_name` then
- * `parameter_value` is added to the existing ones.
+ * If there is already a parameter called ``parameter_name`` then
+ * ``parameter_value`` is added to the existing ones.
*
* @param parameter_name the name of the parameter
* @param parameter_value the value to add
@@ -195,7 +195,7 @@ public abstract class Folks.AbstractFieldDetails<T> : Object
/**
* Set the value of a parameter.
*
- * Sets the parameter called `parameter_name` to be `parameter_value`.
+ * Sets the parameter called ``parameter_name`` to be ``parameter_value``.
* If there were already parameters with the same name they are replaced.
*
* @param parameter_name the name of the parameter
@@ -212,7 +212,7 @@ public abstract class Folks.AbstractFieldDetails<T> : Object
/**
* Extend the existing parameters.
*
- * Merge the parameters from `additional` into the existing ones.
+ * Merge the parameters from ``additional`` into the existing ones.
*
* @param additional the parameters to add
*
diff --git a/folks/alias-details.vala b/folks/alias-details.vala
index 953c902..38237cd 100644
--- a/folks/alias-details.vala
+++ b/folks/alias-details.vala
@@ -38,7 +38,7 @@ public interface Folks.AliasDetails : Object
* An alias is a user-given name, to be used in UIs as the sole way to
* represent the contact to the user.
*
- * This may not be `null`: an empty string represents an unset alias.
+ * This may not be ``null``: an empty string represents an unset alias.
*/
public abstract string alias { get; set; }
diff --git a/folks/anti-linkable.vala b/folks/anti-linkable.vala
index a40798e..23d42c8 100644
--- a/folks/anti-linkable.vala
+++ b/folks/anti-linkable.vala
@@ -40,7 +40,7 @@ public interface Folks.AntiLinkable : Folks.Persona
* not be linked to this { link Persona}, even if their linkable properties
* match.
*
- * No UIDs may be `null`. Well-formed but non-existent UIDs (i.e. UIDs which
+ * No UIDs may be ``null``. Well-formed but non-existent UIDs (i.e. UIDs which
* can be successfully parsed, but which don't currently correspond to a
* { link Persona} instance) are permitted, as personas may appear and
* disappear over time.
@@ -84,11 +84,11 @@ public interface Folks.AntiLinkable : Folks.Persona
/**
* Check for an anti-link with another persona.
*
- * This will return `true` if `other_persona`'s UID is listed in this
+ * This will return ``true`` if ``other_persona``'s UID is listed in this
* persona's anti-links set. Note that this check is not symmetric.
*
* @param other_persona the persona to check is anti-linked
- * @return `true` if an anti-link exists, `false` otherwise
+ * @return ``true`` if an anti-link exists, ``false`` otherwise
* @since 0.7.3
*/
public bool has_anti_link_with_persona (Persona other_persona)
@@ -99,7 +99,7 @@ public interface Folks.AntiLinkable : Folks.Persona
/**
* Add anti-links to other personas.
*
- * The UIDs of all personas in `other_personas` will be added to this
+ * The UIDs of all personas in ``other_personas`` will be added to this
* persona's anti-links set and the changes propagated to backends.
*
* Any attempt to anti-link a persona with itself is not an error, but is
@@ -132,7 +132,7 @@ public interface Folks.AntiLinkable : Folks.Persona
/**
* Remove anti-links to other personas.
*
- * The UIDs of all personas in `other_personas` will be removed from this
+ * The UIDs of all personas in ``other_personas`` will be removed from this
* persona's anti-links set and the changes propagated to backends.
*
* @param other_personas the personas to remove anti-links from this one
diff --git a/folks/avatar-cache.vala b/folks/avatar-cache.vala
index 579d13c..3536f0a 100644
--- a/folks/avatar-cache.vala
+++ b/folks/avatar-cache.vala
@@ -105,7 +105,7 @@ public class Folks.AvatarCache : Object
* Fetch an avatar from the cache by its globally unique ID.
*
* @param id the globally unique ID for the avatar
- * @return Avatar from the cache, or `null` if it doesn't exist in the cache
+ * @return Avatar from the cache, or ``null`` if it doesn't exist in the cache
* @throws GLib.Error if checking for existence of the cache file failed
* @since 0.6.0
*/
diff --git a/folks/avatar-details.vala b/folks/avatar-details.vala
index aac38b2..edd2b0c 100644
--- a/folks/avatar-details.vala
+++ b/folks/avatar-details.vala
@@ -35,7 +35,7 @@ public interface Folks.AvatarDetails : Object
/**
* An avatar for the contact.
*
- * The avatar may be `null` if unset. Otherwise, the image data may be
+ * The avatar may be ``null`` if unset. Otherwise, the image data may be
* asynchronously loaded using the methods of the { link GLib.LoadableIcon}
* implementation.
*
@@ -51,7 +51,7 @@ public interface Folks.AvatarDetails : Object
* notification and will only return once the avatar has been written to the
* relevant backing store (or the operation's failed).
*
- * @param avatar the new avatar (or `null` to unset the avatar)
+ * @param avatar the new avatar (or ``null`` to unset the avatar)
* @throws PropertyError if setting the avatar failed
* @since 0.6.2
*/
diff --git a/folks/backend-store.vala b/folks/backend-store.vala
index 34e6376..a63563a 100644
--- a/folks/backend-store.vala
+++ b/folks/backend-store.vala
@@ -271,9 +271,9 @@ public class Folks.BackendStore : Object {
/**
* Find, load, and prepare all backends which are not disabled.
*
- * Backends will be searched for in the path given by the `FOLKS_BACKEND_PATH`
- * environment variable, if it's set. If it's not set, backends will be
- * searched for in a path set at compilation time.
+ * Backends will be searched for in the path given by the
+ * ``FOLKS_BACKEND_PATH`` environment variable, if it's set. If it's not set,
+ * backends will be searched for in a path set at compilation time.
*
* @throws GLib.Error currently unused
*/
@@ -513,7 +513,7 @@ public class Folks.BackendStore : Object {
* reference count is increased.
*
* @param name the backend name to retrieve
- * @return the backend, or `null` if none could be found
+ * @return the backend, or ``null`` if none could be found
*
* @since 0.3.5
*/
diff --git a/folks/backend.vala b/folks/backend.vala
index 89f7264..ec6613d 100644
--- a/folks/backend.vala
+++ b/folks/backend.vala
@@ -60,9 +60,9 @@ public abstract class Folks.Backend : Object
* { link PersonaStore}s that it originally knows about have been loaded.
*
* It's guaranteed that this property's value will only ever change after
- * { link Backend.is_prepared} has changed to `true`.
+ * { link Backend.is_prepared} has changed to ``true``.
*
- * When { link Backend.unprepare} is called, this will be reset to `false`.
+ * When { link Backend.unprepare} is called, this will be reset to ``false``.
*
* @since 0.6.2
*/
diff --git a/folks/birthday-details.vala b/folks/birthday-details.vala
index 7c85d00..ba5f207 100644
--- a/folks/birthday-details.vala
+++ b/folks/birthday-details.vala
@@ -36,7 +36,7 @@ public interface Folks.BirthdayDetails : Object
* The birthday of the { link Persona} and { link Individual}. This
* is assumed to be in UTC.
*
- * If this is `null`, the contact's birthday isn't known.
+ * If this is ``null``, the contact's birthday isn't known.
*
* @since 0.4.0
*/
@@ -50,7 +50,7 @@ public interface Folks.BirthdayDetails : Object
* notification and will only return once the birthday has been written to the
* relevant backing store (or the operation's failed).
*
- * @param birthday the new birthday (or `null` to unset the birthday)
+ * @param birthday the new birthday (or ``null`` to unset the birthday)
* @throws PropertyError if setting the birthday failed
* @since 0.6.2
*/
@@ -65,7 +65,7 @@ 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. The semantics of the
+ * If this is ``null``, the birthday event is unknown. The semantics of the
* event ID are left unspecified by folks.
*
* @since 0.4.0
@@ -80,7 +80,8 @@ public interface Folks.BirthdayDetails : Object
* error notification and will only return once the event has been written to
* the relevant backing store (or the operation's failed).
*
- * @param event_id the new birthday event ID (or `null` to unset the event ID)
+ * @param event_id the new birthday event ID (or ``null`` to unset the event
+ * ID)
* @throws PropertyError if setting the birthday event ID failed
* @since 0.6.2
*/
diff --git a/folks/email-details.vala b/folks/email-details.vala
index e8ea513..56e2bac 100644
--- a/folks/email-details.vala
+++ b/folks/email-details.vala
@@ -40,8 +40,8 @@ public class Folks.EmailFieldDetails : AbstractFieldDetails<string>
* @param value the value of the field, which should be a valid, non-empty
* e-mail address
* @param parameters initial parameters. See
- * { link AbstractFieldDetails.parameters}. A `null` value is equivalent to an
- * empty map of parameters.
+ * { link AbstractFieldDetails.parameters}. A ``null`` value is equivalent to
+ * an empty map of parameters.
*
* @return a new EmailFieldDetails
*
diff --git a/folks/favourite-details.vala b/folks/favourite-details.vala
index 361187a..0d76b6c 100644
--- a/folks/favourite-details.vala
+++ b/folks/favourite-details.vala
@@ -45,7 +45,8 @@ public interface Folks.FavouriteDetails : Object
* notification and will only return once the favouriteness has been written
* to the relevant backing store (or the operation's failed).
*
- * @param is_favourite `true` if the contact is a favourite; `false` otherwise
+ * @param is_favourite ``true`` if the contact is a favourite; ``false``
+ * otherwise
* @throws PropertyError if setting the favouriteness failed
* @since 0.6.2
*/
diff --git a/folks/group-details.vala b/folks/group-details.vala
index 95a83fe..cbb19e1 100644
--- a/folks/group-details.vala
+++ b/folks/group-details.vala
@@ -130,8 +130,8 @@ public interface Folks.GroupDetails : Object
/**
* Add or remove the contact from the specified group.
*
- * If `is_member` is `true`, the contact will be added to the `group`. If
- * it is `false`, they will be removed from the `group`.
+ * If ``is_member`` is ``true``, the contact will be added to the ``group``.
+ * If it is ``false``, they will be removed from the ``group``.
*
* @param group a freeform group identifier
* @param is_member whether the contact should be a member of the group
diff --git a/folks/im-details.vala b/folks/im-details.vala
index f891e36..70ea64f 100644
--- a/folks/im-details.vala
+++ b/folks/im-details.vala
@@ -49,8 +49,8 @@ public class Folks.ImFieldDetails : AbstractFieldDetails<string>
* @param value the value of the field, which should be a valid, non-empty
* IM address
* @param parameters initial parameters. See
- * { link AbstractFieldDetails.parameters}. A `null` value is equivalent to an
- * empty map of parameters.
+ * { link AbstractFieldDetails.parameters}. A ``null`` value is equivalent to
+ * an empty map of parameters.
*
* @return a new ImFieldDetails
*
diff --git a/folks/individual-aggregator.vala b/folks/individual-aggregator.vala
index 9ea288e..4d9406e 100644
--- a/folks/individual-aggregator.vala
+++ b/folks/individual-aggregator.vala
@@ -134,7 +134,7 @@ public class Folks.IndividualAggregator : Object
* quiescent state.
*
* It's guaranteed that this property's value will only ever change after
- * { link IndividualAggregator.is_prepared} has changed to `true`.
+ * { link IndividualAggregator.is_prepared} has changed to ``true``.
*
* @since 0.6.2
*/
@@ -150,8 +150,8 @@ public class Folks.IndividualAggregator : Object
* by:
*
* - the FOLKS_PRIMARY_STORE env var (mostly for debugging)
- * - the GSettings key set in `_PRIMARY_STORE_CONFIG_KEY` (system set store)
- * - going with the `key-file` or `eds` store as the fall-back option
+ * - the GSettings key set in ``_PRIMARY_STORE_CONFIG_KEY`` (system set store)
+ * - going with the ``key-file`` or ``eds`` store as the fall-back option
*
* @since 0.5.0
*/
@@ -237,7 +237,7 @@ public class Folks.IndividualAggregator : Object
* mappings from the old individuals to the single new individual which
* replaces them (i.e. each of the old individuals will map to the same new
* individual). This new individual is the one which will be specified as the
- * `replacement_individual` in the { link Individual.removed} signal for the
+ * ``replacement_individual`` in the { link Individual.removed} signal for the
* old individuals.
*
* Individuals which have been unlinked will be listed in the multi-map as
@@ -245,11 +245,11 @@ public class Folks.IndividualAggregator : Object
* which replace it.
*
* Individuals which have been added will be listed in the multi-map as a
- * mapping from `null` to the set of added individuals. If `null` doesn't
+ * mapping from ``null`` to the set of added individuals. If ``null`` doesn't
* map to anything, no individuals have been added to the aggregator.
*
* Individuals which have been removed will be listed in the multi-map as
- * mappings from the removed individual to `null`.
+ * mappings from the removed individual to ``null``.
*
* This will not be emitted until after { link IndividualAggregator.prepare}
* has been called.
@@ -611,7 +611,7 @@ public class Folks.IndividualAggregator : Object
* @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`);
+ * ``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
@@ -645,7 +645,7 @@ public class Folks.IndividualAggregator : Object
* @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`)
+ * individual (which is guaranteed to at least equal ``min_threshold``)
*
* @since 0.5.1
*/
@@ -761,7 +761,7 @@ public class Folks.IndividualAggregator : Object
/* We use the configured PersonaStore as the primary PersonaStore.
*
- * If the type_id is `eds` we *must* know the actual store
+ * If the type_id is ``eds`` we *must* know the actual store
* (address book) we are talking about or we might end up using
* a random store on every run.
*/
@@ -1004,13 +1004,13 @@ public class Folks.IndividualAggregator : Object
PersonaStoreTrust trust_level = persona.store.trust_level;
/* These are the Individuals whose Personas will be linked together
- * to form the `final_individual`.
+ * to form the ``final_individual``.
* Since a given Persona can only be part of one Individual, and the
* code in Persona._set_personas() ensures that there are no duplicate
* Personas in a given Individual, ensuring that there are no
- * duplicate Individuals in `candidate_inds` (by using a
+ * duplicate Individuals in ``candidate_inds`` (by using a
* HashSet) guarantees that there will be no duplicate Personas
- * in the `final_individual`. */
+ * in the ``final_individual``. */
HashSet<Individual> candidate_inds = new HashSet<Individual> ();
var final_personas = new HashSet<Persona> ();
@@ -1698,8 +1698,8 @@ public class Folks.IndividualAggregator : Object
}
/**
- * Add a new persona in the given { link PersonaStore} based on the `details`
- * provided.
+ * Add a new persona in the given { link PersonaStore} based on the
+ * ``details`` provided.
*
* If the target store is offline, this function will throw
* { link IndividualAggregatorError.STORE_OFFLINE}. It's the responsibility of
@@ -1713,15 +1713,15 @@ public class Folks.IndividualAggregator : Object
* * message - a user-readable message to pass to the persona being added
*
* If a { link Persona} with the given details already exists in the store, no
- * error will be thrown and this function will return `null`.
+ * error will be thrown and this function will return ``null``.
*
* @param parent an optional { link Individual} to add the new { link Persona}
* to. This persona will be appended to its ordered list of personas.
* @param persona_store the { link PersonaStore} to add the persona to
* @param details a key-value map of details to use in creating the new
* { link Persona}
- * @return the new { link Persona} or `null` if the corresponding
- * { link Persona} already existed. If non-`null`, the new { link Persona}
+ * @return the new { link Persona} or ``null`` if the corresponding
+ * { link Persona} already existed. If non-``null``, the new { link Persona}
* will also be added to a new or existing { link Individual} as necessary.
* @throws IndividualAggregatorError.STORE_OFFLINE if the persona store was
* offline
@@ -1900,7 +1900,7 @@ public class Folks.IndividualAggregator : Object
private HashTable<string, Value?> _build_linking_details (
Set<Persona> personas)
{
- /* `protocols_addrs_set` will be passed to the new Kf.Persona */
+ /* ``protocols_addrs_set`` will be passed to the new Kf.Persona */
var protocols_addrs_set = new HashMultiMap<string, ImFieldDetails> (
null, null,
(GLib.HashFunc) ImFieldDetails.hash,
@@ -2073,7 +2073,7 @@ public class Folks.IndividualAggregator : Object
* { link Individual}.
*
* This makes sure that there is at least one { link Persona} in the
- * individual which has `property_name` in its
+ * individual which has ``property_name`` in its
* { link Persona.writeable_properties}. If no such persona exists in the
* individual, a new one will be created and linked to the individual. (Note
* that due to the design of the aggregator, this will result in the previous
@@ -2086,7 +2086,7 @@ public class Folks.IndividualAggregator : Object
* { link IndividualAggregatorError.PROPERTY_NOT_WRITEABLE} error will be
* thrown.
*
- * @param individual the individual for which `property_name` should be
+ * @param individual the individual for which ``property_name`` should be
* writeable
* @param property_name the name of the property which needs to be writeable
* (this should be in lower case using hyphens, e.g. âweb-service-addressesâ)
@@ -2095,7 +2095,7 @@ public class Folks.IndividualAggregator : Object
* @throws IndividualAggregatorError.NO_PRIMARY_STORE if no primary store was
* configured for this individual aggregator
* @throws IndividualAggregatorError.PROPERTY_NOT_WRITEABLE if the given
- * `property_name` referred to a non-writeable property
+ * ``property_name`` referred to a non-writeable property
* @throws IndividualAggregatorError if adding a new persona (using
* { link IndividualAggregator.add_persona_from_details}) failed, or if
* linking personas (using { link IndividualAggregator.link_personas}) failed
@@ -2204,8 +2204,8 @@ public class Folks.IndividualAggregator : Object
/**
* Look up an individual in the aggregator.
*
- * This returns the { link Individual} with the given `id` if it exists in
- * the aggregator, and `null` otherwise.
+ * This returns the { link Individual} with the given ``id`` if it exists in
+ * the aggregator, and ``null`` otherwise.
*
* In future, when lazy-loading of individuals' properties is added to folks,
* this method guarantees to load all properties of the individual, even if
@@ -2216,7 +2216,7 @@ public class Folks.IndividualAggregator : Object
* that case.
*
* @param id ID of the individual to look up
- * @return individual with `id`, or `null` if no such individual was found
+ * @return individual with ``id``, or ``null`` if no such individual was found
* @throws GLib.Error from { link IndividualAggregator.prepare}
*
* @since 0.7.0
diff --git a/folks/individual.vala b/folks/individual.vala
index 18015dc..d0bd428 100644
--- a/folks/individual.vala
+++ b/folks/individual.vala
@@ -152,9 +152,9 @@ public class Folks.Individual : Object,
* Setting this property is only guaranteed to succeed (and be written to
* the backing store) if
* { link IndividualAggregator.ensure_individual_property_writeable} has been
- * called successfully on the individual for the property name `avatar`.
+ * called successfully on the individual for the property name ``avatar``.
*
- * @param avatar the new avatar (or `null` to unset the avatar)
+ * @param avatar the new avatar (or ``null`` to unset the avatar)
* @throws PropertyError if setting the avatar failed
* @since 0.6.3
*/
@@ -232,22 +232,22 @@ public class Folks.Individual : Object,
*
* 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`.
+ * this is ``true``.
*
* It is //not// guaranteed that every { link Persona} in the Individual has
* its { link Persona.is_user} set to the same value as the Individual. For
* example, the user could own two Telepathy accounts, and have added the
* other account as a contact in each account. The accounts will expose a
* { link Persona} for the user (which will have { link Persona.is_user} set
- * to `true`) //and// a { link Persona} for the contact for the other account
- * (which will have { link Persona.is_user} set to `false`).
+ * to ``true``) //and// a { link Persona} for the contact for the other
+ * account (which will have { link Persona.is_user} set to ``false``).
*
- * It is guaranteed that iff this property is set to `true` on an Individual,
- * there will be at least one { link Persona} in the Individual with its
- * { link Persona.is_user} set to `true`.
+ * It is guaranteed that iff this property is set to ``true`` on an
+ * Individual, there will be at least one { link Persona} in the Individual
+ * with its { link Persona.is_user} set to ``true``.
*
* It is guaranteed that there will only ever be one Individual with this
- * property set to `true`.
+ * property set to ``true``.
*
* @since 0.3.0
*/
@@ -279,7 +279,8 @@ public class Folks.Individual : Object,
* should unreference it and remove it from their UI.
*
* @param replacement_individual the individual which has replaced this one
- * due to linking, or `null` if this individual was removed for another reason
+ * due to linking, or ``null`` if this individual was removed for another
+ * reason
* @since 0.1.13
*/
public signal void removed (Individual? replacement_individual);
@@ -604,7 +605,7 @@ public class Folks.Individual : Object,
/**
* Whether this Individual is a user-defined favourite.
*
- * This property is `true` if any of this Individual's { link Persona}s are
+ * This property is ``true`` if any of this Individual's { link Persona}s are
* favourites).
*/
[CCode (notify = false)]
@@ -995,8 +996,8 @@ public class Folks.Individual : Object,
/**
* Add or remove the Individual from the specified group.
*
- * If `is_member` is `true`, the Individual will be added to the `group`. If
- * it is `false`, they will be removed from the `group`.
+ * If ``is_member`` is ``true``, the Individual will be added to the
+ * ``group``. If it is ``false``, they will be removed from the ``group``.
*
* The group membership change will propagate to every { link Persona} in
* the Individual.
@@ -1079,11 +1080,11 @@ public class Folks.Individual : Object,
* Create a new Individual.
*
* The Individual can optionally be seeded with the { link Persona}s in
- * `personas`. Otherwise, it will have to have personas added using the
+ * ``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 Folks.Individual} with, or `null`
+ * { link Folks.Individual} with, or ``null``
* @return a new Individual
*
* @since 0.5.1
@@ -1230,17 +1231,17 @@ public class Folks.Individual : Object,
* this individual, with the highest-positioned persona (the âgreatestâ
* persona in the total order) finally being passed to the setter function to
* use in updating the individual's value for the given property. i.e. If
- * `compare_func(a, b)` is called and returns > 0, persona `a` will be passed
- * to the setter.
+ * ``compare_func(a, b)`` is called and returns > 0, persona ``a`` will be
+ * passed to the setter.
*
- * At a level above `compare_func`, the function always prefers personas from
- * the primary store (see { link IndividualAggregator.primary_store}) over
- * those which aren't.
+ * At a level above ``compare_func``, the function always prefers personas
+ * from the primary store (see { link IndividualAggregator.primary_store})
+ * over those which aren't.
*
* Note that if a suitable persona isn't found in the individual (if, for
* example, no personas in the individual implement the desired interface),
- * `null` will be passed to `setter`, which should then set the individual's
- * property to a default value.
+ * ``null`` will be passed to ``setter``, which should then set the
+ * individual's property to a default value.
*
* @param interface_type the type of interface which all personas under
* consideration must implement ({ link Persona} to select all personas)
@@ -2223,14 +2224,16 @@ public class Folks.Individual : Object,
/**
* Anti-linked with a persona?
*
- * Check whether this individual is anti-linked to { link Persona} `p` at all.
- * If so, `true` will be returned â `false` will be returned otherwise.
+ * Check whether this individual is anti-linked to { link Persona} ``p`` at
+ * all. 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.
*
* @param p persona to check for anti-links with
- * @return `true` if this individual is anti-linked with persona `p`; `false`
+ * @return ``true`` if this individual is anti-linked with persona ``p``;
+ * ``false``
* otherwise
* @since 0.7.3
*/
@@ -2256,15 +2259,15 @@ 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 Folks.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.
*
* @param i individual to check for anti-links with
- * @return `true` if this individual is anti-linked with individual `i`;
- * `false` otherwise
+ * @return ``true`` if this individual is anti-linked with individual ``i``;
+ * ``false`` otherwise
* @since 0.7.3
*/
public bool has_anti_link_with_individual (Individual i)
diff --git a/folks/name-details.vala b/folks/name-details.vala
index 22217cd..956346c 100644
--- a/folks/name-details.vala
+++ b/folks/name-details.vala
@@ -28,7 +28,7 @@ using GLib;
*
* 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
@@ -110,7 +110,7 @@ public class Folks.StructuredName : Object
/**
* Create a StructuredName.
*
- * You can pass `null` if a component is not set.
+ * You can pass ``null`` if a component is not set.
*
* @param family_name the family (last) name
* @param given_name the given (first) name
@@ -136,7 +136,7 @@ public class Folks.StructuredName : Object
*
* Shorthand for the common case of just having the family and given
* name of a contact. It's equivalent to calling
- * { link StructuredName.StructuredName} and passing `null` for all
+ * { link StructuredName.StructuredName} and passing ``null`` for all
* the other components.
*
* @param family_name the family (last) name
@@ -154,7 +154,7 @@ public class Folks.StructuredName : Object
/**
* Whether none of the components is set.
*
- * @return `true` if all the components are the empty string, `false`
+ * @return ``true`` if all the components are the empty string, ``false``
* otherwise.
*
* @since 0.3.5
@@ -172,7 +172,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`
+ * @return ``true`` if all the components are the same, ``false``
* otherwise.
*
* @since 0.5.0
@@ -217,9 +217,9 @@ public interface Folks.NameDetails : Object
* The contact name split in its constituent parts.
*
* Note that most of the time the structured name is not set (i.e.
- * it's `null`) or just some of the components are set.
+ * it's ``null``) or just some of the components are set.
* The components are immutable. To get notification of changes of
- * the structured name, you just have to connect to the `notify` signal
+ * the structured name, you just have to connect to the ``notify`` signal
* of this property.
*
* @since 0.3.5
@@ -234,7 +234,7 @@ public interface Folks.NameDetails : Object
* notification and will only return once the name has been written to the
* relevant backing store (or the operation's failed).
*
- * @param name the structured name (`null` to unset it)
+ * @param name the structured name (``null`` to unset it)
* @throws PropertyError if setting the structured name failed
* @since 0.6.2
*/
@@ -256,8 +256,8 @@ public interface Folks.NameDetails : Object
* The full name could or could not contain additional names (like a
* middle name), prefixes or suffixes.
*
- * The full name must not be `null`: the empty string represents an unset full
- * name.
+ * The full name must not be ``null``: the empty string represents an unset
+ * full name.
*
* @since 0.3.5
*/
@@ -294,7 +294,7 @@ public interface Folks.NameDetails : Object
* address book when updating the information a contact has specified about
* themselves.
*
- * The nickname must not be `null`: the empty string represents an unset
+ * The nickname must not be ``null``: the empty string represents an unset
* nickname.
*
* @since 0.3.5
diff --git a/folks/note-details.vala b/folks/note-details.vala
index f7624df..5ca675d 100644
--- a/folks/note-details.vala
+++ b/folks/note-details.vala
@@ -59,9 +59,9 @@ public class Folks.NoteFieldDetails : AbstractFieldDetails<string>
* @param value the value of the field, which should be a non-empty free-form
* UTF-8 string as entered by the user
* @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
+ * { 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/object-cache.vala b/folks/object-cache.vala
index 77c7309..b33a4fe 100644
--- a/folks/object-cache.vala
+++ b/folks/object-cache.vala
@@ -62,8 +62,8 @@ public abstract class Folks.ObjectCache<T> : Object
* changes, this may be modified to take a version parameter.
*
* @param object_version the version of the object format to use, or
- * `uint8.MAX` for the latest version
- * @return variant type for that object version, or `null` if the version is
+ * ``uint8.MAX`` for the latest version
+ * @return variant type for that object version, or ``null`` if the version is
* unsupported
* @since 0.6.0
*/
@@ -81,20 +81,20 @@ public abstract class Folks.ObjectCache<T> : Object
protected abstract uint8 get_serialised_object_version ();
/**
- * Serialise the given `object` to a { link GLib.Variant} and return the
+ * 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`
+ * @return serialised form of ``object``
*
* @since 0.6.0
*/
protected abstract Variant serialise_object (T object);
/**
- * Deserialise the given `variant` to a new instance of an object. The variant
- * is guaranteed to have the type returned by
+ * 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}.
*
* @param variant the serialised form to deserialise
@@ -133,7 +133,8 @@ public abstract class Folks.ObjectCache<T> : Object
/**
* Create a new cache instance using the given type ID and ID. This is
- * protected as the `type_id` will typically be set statically by subclasses.
+ * protected as the ``type_id`` will typically be set statically by
+ * subclasses.
*
* @param type_id A string identifying the type of object being cached. This
* has to be suitable for use as a directory name; i.e. lower case,
@@ -169,18 +170,19 @@ public abstract class Folks.ObjectCache<T> : Object
/**
* Load a set of objects from the cache and return them as a new set. If the
- * cache file doesn't exist, `null` will be returned. An empty set will be
+ * cache file doesn't exist, ``null`` will be returned. An empty set will be
* returned if the cache file existed but was empty (i.e. was stored with
* an empty set originally).
*
- * Loading the objects can be cancelled using `cancellable`. If it is, `null`
- * will be returned.
+ * Loading the objects can be cancelled using ``cancellable``. If it is,
+ * ``null`` will be returned.
*
* If any errors are encountered while loading the objects, warnings will be
- * logged as appropriate and `null` will be returned.
+ * logged as appropriate and ``null`` will be returned.
*
- * @param cancellable A { link GLib.Cancellable} for the operation, or `null`.
- * @return A set of objects from the cache, or `null`.
+ * @param cancellable A { link GLib.Cancellable} for the operation, or
+ * ``null``.
+ * @return A set of objects from the cache, or ``null``.
*
* @since 0.6.0
*/
@@ -318,13 +320,14 @@ public abstract class Folks.ObjectCache<T> : Object
* objects in the cache, or creating the cache file from scratch if it didn't
* previously exist.
*
- * Storing the objects can be cancelled using `cancellable`. If it is, the
+ * Storing the objects can be cancelled using ``cancellable``. If it is, the
* cache will be left in a consistent state, but may be storing the old set
* of objects or the new set.
*
* @param objects A set of objects to store. This may be empty, but may not
- * be `null`.
- * @param cancellable A { link GLib.Cancellable} for the operation, or `null`.
+ * be ``null``.
+ * @param cancellable A { link GLib.Cancellable} for the operation, or
+ * ``null``.
*
* @since 0.6.0
*/
diff --git a/folks/persona-store.vala b/folks/persona-store.vala
index cad7376..22a3089 100644
--- a/folks/persona-store.vala
+++ b/folks/persona-store.vala
@@ -80,7 +80,7 @@ public errordomain Folks.PersonaStoreError
/**
* Such an operation may not be performed on a { link Persona} with
- * { link Persona.is_user} set to `true`.
+ * { link Persona.is_user} set to ``true``.
*
* @since 0.3.0
*/
@@ -118,7 +118,7 @@ public errordomain Folks.PersonaStoreError
/**
* Such an operation may only be performed on a { link Persona} with
- * { link Persona.is_user} set to `true`.
+ * { link Persona.is_user} set to ``true``.
*
* @since 0.6.4
*/
@@ -369,7 +369,8 @@ public abstract class Folks.PersonaStore : Object
* the details param of { link PersonaStore.add_persona_from_details}.
*
* @param detail the { link PersonaDetail} to lookup
- * @return the corresponding property name, or `null` if `detail` is invalid
+ * @return the corresponding property name, or ``null`` if ``detail`` is
+ * invalid
*
* @since 0.5.0
*/
@@ -470,7 +471,7 @@ public abstract class Folks.PersonaStore : Object
* The human-readable, service-specific name used to represent the
* PersonaStore to the user.
*
- * For example: `foo@@xmpp.example.org`.
+ * For example: ``foo@@xmpp.example.org``.
*
* This should be used whenever the user needs to be presented with a
* familiar, service-specific name. For instance, in a prompt for the user to
@@ -558,7 +559,7 @@ public abstract class Folks.PersonaStore : Object
* it originally knows about have been loaded.
*
* It's guaranteed that this property's value will only ever change after
- * { link IndividualAggregator.is_prepared} has changed to `true`.
+ * { link IndividualAggregator.is_prepared} has changed to ``true``.
*
* @since 0.6.2
*/
@@ -571,8 +572,8 @@ public abstract class Folks.PersonaStore : Object
* changes to the { link Individual}s containing them, and those changes then
* be written out to the relevant backing store.
*
- * If this property is `false`, it doesn't mean that { link Persona}s in this
- * persona store aren't writeable at all. If their properties are updated
+ * If this property is ``false``, it doesn't mean that { link Persona}s in
+ * this persona store aren't writeable at all. If their properties are updated
* through the { link Persona}, rather than through the { link Individual}
* containing that persona, changes may be propagated to the backing store.
*
@@ -686,7 +687,7 @@ public abstract class Folks.PersonaStore : Object
* Add a new { link Persona} to the PersonaStore.
*
* The { link Persona} will be created by the PersonaStore backend from the
- * key-value pairs given in `details`.
+ * key-value pairs given in ``details``.
*
* All additions through this function will later be emitted through the
* personas-changed signal to be notified of the new { link Persona}. The
@@ -705,13 +706,13 @@ public abstract class Folks.PersonaStore : Object
* can either support a subset or superset of the suggested defaults.
*
* If a { link Persona} with the given details already exists in the store, no
- * error will be thrown and this function will return `null`.
+ * error will be thrown and this function will return ``null``.
*
* @param details a key-value map of details to use in creating the new
* { link Persona}
*
- * @return the new { link Persona} or `null` if the corresponding Persona
- * already existed. If non-`null`, the new { link Persona} will also be
+ * @return the new { link Persona} or ``null`` if the corresponding Persona
+ * already existed. If non-``null``, the new { link Persona} will also be
* amongst the { link Persona}(s) in a future emission of
* { link PersonaStore.personas_changed}.
* @throws PersonaStoreError if adding the persona failed
diff --git a/folks/persona.vala b/folks/persona.vala
index 41e9ce8..9cb17da 100644
--- a/folks/persona.vala
+++ b/folks/persona.vala
@@ -106,7 +106,7 @@ public abstract class Folks.Persona : Object
* The human-readable, service-specific universal ID used to represent the
* Persona.
*
- * For example: `foo@@xmpp.example.org`.
+ * For example: ``foo@@xmpp.example.org``.
*
* This should be used whenever the user needs to be presented with a
* familiar, service-specific ID. For instance, in a prompt for the user to
@@ -124,7 +124,7 @@ public abstract class Folks.Persona : Object
* Whether the Persona is the user.
*
* Iff the Persona represents the user (the person who owns the account in
- * the respective backend) this is `true`.
+ * the respective backend) this is ``true``.
*
* @since 0.3.0
*/
@@ -148,7 +148,7 @@ public abstract class Folks.Persona : Object
/**
* The { link Individual} which contains this Persona.
*
- * This may be `null`, but should only ever be so when the Persona has just
+ * This may be ``null``, but should only ever be so when the Persona has just
* been created, when its { link PersonaStore} is being destroyed, or when
* it's moving between { link Individual}s.
*
@@ -224,7 +224,7 @@ public abstract class Folks.Persona : Object
*
* This is a callback provided by the { link IndividualAggregator} whenever
* a { link Persona.linkable_property_to_links} method is called, which should
- * be called by the `linkable_property_to_links` implementation for each
+ * be called by the ``linkable_property_to_links`` implementation for each
* linkable-property-to-individual mapping it wants to add or remove in the
* aggregator.
*
@@ -242,7 +242,7 @@ public abstract class Folks.Persona : Object
* This is a virtual method, to be overridden by subclasses of { link Persona}
* who have linkable properties. Each of their linkable properties should be
* handled by their implementation of this function, examining the current
- * value of the property and calling `callback` with one or more mapping
+ * value of the property and calling ``callback`` with one or more mapping
* strings for the property's value. Each of these mapping strings will be
* added to the { link IndividualAggregator}'s link map, related to the
* { link Individual} instance which contains this { link Persona}.
diff --git a/folks/phone-details.vala b/folks/phone-details.vala
index 311b085..a33cf4a 100644
--- a/folks/phone-details.vala
+++ b/folks/phone-details.vala
@@ -57,8 +57,8 @@ public class Folks.PhoneFieldDetails : AbstractFieldDetails<string>
* @param value the value of the field, which should be a non-empty phone
* number (no particular format is mandated)
* @param parameters initial parameters. See
- * { link AbstractFieldDetails.parameters}. A `null` value is equivalent to a
- * empty map of parameters.
+ * { link AbstractFieldDetails.parameters}. A ``null`` value is equivalent to
+ * an empty map of parameters.
*
* @return a new PhoneFieldDetails
*
@@ -129,11 +129,11 @@ public class Folks.PhoneFieldDetails : AbstractFieldDetails<string>
*
* 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``
*
- * @return the normalised form of `number`
+ * @return the normalised form of ``number``
*
* @since 0.6.0
*/
diff --git a/folks/postal-address-details.vala b/folks/postal-address-details.vala
index 6695450..5e0906d 100644
--- a/folks/postal-address-details.vala
+++ b/folks/postal-address-details.vala
@@ -27,7 +27,7 @@ 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
@@ -145,7 +145,7 @@ public class Folks.PostalAddress : Object
/**
* Create a PostalAddress.
*
- * You can pass `null` if a component is not set.
+ * You can pass ``null`` if a component is not set.
*
* @param po_box the PO Box
* @param extension the address extension
@@ -176,7 +176,7 @@ public class Folks.PostalAddress : Object
/**
* Whether none of the components is set.
*
- * @return `true` if all the components are the empty string, `false`
+ * @return ``true`` if all the components are the empty string, ``false``
* otherwise.
*
* @since 0.6.7
@@ -195,13 +195,13 @@ public class Folks.PostalAddress : Object
/**
* Compare if two postal addresses are equal. Addresses are equal if all their
- * components are equal (where `null` compares equal only with `null`) and
+ * components are equal (where ``null`` compares equal only with ``null``) and
* they have the same set of types (or both have no types).
*
* This does not factor in the { link PostalAddress.uid}.
*
* @param with another postal address to compare with
- * @return `true` if the addresses are equal, `false` otherwise
+ * @return ``true`` if the addresses are equal, ``false`` otherwise
*/
public bool equal (PostalAddress with)
{
@@ -268,8 +268,8 @@ public class Folks.PostalAddressFieldDetails :
*
* @param value the value of the field, a non-empty { link PostalAddress}
* @param parameters initial parameters. See
- * { link AbstractFieldDetails.parameters}. A `null` value is equivalent to an
- * empty map of parameters.
+ * { link AbstractFieldDetails.parameters}. A ``null`` value is equivalent to
+ * an empty map of parameters.
*
*
* @return a new PostalAddressFieldDetails
diff --git a/folks/presence-details.vala b/folks/presence-details.vala
index 82e8be6..bca24da 100644
--- a/folks/presence-details.vala
+++ b/folks/presence-details.vala
@@ -73,8 +73,8 @@ public enum Folks.PresenceType
* their current availability, such as for chatting.
*
* If the { link Backend} providing the { link Persona} doesn't support
- * presence, the { link Persona}'s `presence_type` will be set to
- * { link PresenceType.UNSET} and their `presence_message` will be an empty
+ * presence, the { link Persona}'s ``presence_type`` will be set to
+ * { link PresenceType.UNSET} and their ``presence_message`` will be an empty
* string.
*/
public interface Folks.PresenceDetails : Object
@@ -179,8 +179,8 @@ public interface Folks.PresenceDetails : Object
/**
* Compare two { link PresenceType}s.
*
- * `0` will be returned if the types are equal, a positive number will be
- * returned if `type_a` is more available than `type_b`, and a negative
+ * ``0`` will be returned if the types are equal, a positive number will be
+ * 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
@@ -197,11 +197,11 @@ public interface Folks.PresenceDetails : Object
/**
* Whether the contact is online.
*
- * This will be `true` if the contact's presence type is higher than
+ * This will be ``true`` if the contact's presence type is higher than
* { link PresenceType.OFFLINE}, as determined by
* { link PresenceDetails.typecmp}.
*
- * @return `true` if the contact is online, `false` otherwise
+ * @return ``true`` if the contact is online, ``false`` otherwise
*/
public bool is_online ()
{
diff --git a/folks/role-details.vala b/folks/role-details.vala
index 9237b92..2ac3b82 100644
--- a/folks/role-details.vala
+++ b/folks/role-details.vala
@@ -102,7 +102,7 @@ public class Folks.Role : Object
/**
* Whether none of the components is set.
*
- * @return `true` if all the components are the empty string, `false`
+ * @return ``true`` if all the components are the empty string, ``false``
* otherwise.
*
* @since 0.6.7
@@ -120,7 +120,7 @@ public class Folks.Role : Object
*
* @param a a role to compare
* @param b another role to compare
- * @return `true` if the roles are equal, `false` otherwise
+ * @return ``true`` if the roles are equal, ``false`` otherwise
*/
public static bool equal (Role a, Role b)
{
@@ -184,7 +184,7 @@ public class Folks.RoleFieldDetails : AbstractFieldDetails<Role>
*
* @param value the non-empty { link Role} of the field
* @param parameters initial parameters. See
- * { link AbstractFieldDetails.parameters}. A `null` value is equivalent to an
+ * { link AbstractFieldDetails.parameters}. A ``null`` value is equivalent to an
* empty map of parameters.
*
* @return a new RoleFieldDetails
diff --git a/folks/url-details.vala b/folks/url-details.vala
index e743ddc..7a505a1 100644
--- a/folks/url-details.vala
+++ b/folks/url-details.vala
@@ -76,8 +76,8 @@ public class Folks.UrlFieldDetails : AbstractFieldDetails<string>
*
* @param value the value of the field, a non-empty URI
* @param parameters initial parameters. See
- * { link AbstractFieldDetails.parameters}. A `null` value is equivalent to a
- * empty map of parameters.
+ * { link AbstractFieldDetails.parameters}. A ``null`` value is equivalent to
+ * an empty map of parameters.
*
* @return a new UrlFieldDetails
*
diff --git a/folks/utils.vala b/folks/utils.vala
index de6a4a9..817a225 100644
--- a/folks/utils.vala
+++ b/folks/utils.vala
@@ -63,7 +63,7 @@ public class Folks.Utils : Object
*
* @param a a multi-map to compare
* @param b another multi-map to compare
- * @return `true` if the multi-maps are equal, `false` otherwise
+ * @return ``true`` if the multi-maps are equal, ``false`` otherwise
*
* @since 0.6.0
*/
@@ -114,7 +114,7 @@ public class Folks.Utils : Object
*
* @param a a multi-map to compare
* @param b another multi-map to compare
- * @return `true` if the multi-maps are equal, `false` otherwise
+ * @return ``true`` if the multi-maps are equal, ``false`` otherwise
*
* @since 0.6.0
*/
@@ -165,7 +165,7 @@ public class Folks.Utils : Object
*
* @param a a set to compare
* @param b another set to compare
- * @return `true` if the sets are equal, `false` otherwise
+ * @return ``true`` if the sets are equal, ``false`` otherwise
*
* @since 0.6.0
*/
diff --git a/folks/web-service-details.vala b/folks/web-service-details.vala
index ec2c46d..2ed1360 100644
--- a/folks/web-service-details.vala
+++ b/folks/web-service-details.vala
@@ -37,8 +37,8 @@ public class Folks.WebServiceFieldDetails : AbstractFieldDetails<string>
*
* @param value the value of the field, a non-empty web service address
* @param parameters initial parameters. See
- * { link AbstractFieldDetails.parameters}. A `null` value is equivalent to an
- * empty map of parameters.
+ * { link AbstractFieldDetails.parameters}. A ``null`` value is equivalent to
+ * an empty map of parameters.
*
* @return a new WebServiceFieldDetails
*
diff --git a/tests/lib/test-utils.vala b/tests/lib/test-utils.vala
index e2c7661..f6e97cd 100644
--- a/tests/lib/test-utils.vala
+++ b/tests/lib/test-utils.vala
@@ -28,7 +28,7 @@ public class Folks.TestUtils
/**
* Compare the content of two { link LoadableIcon}s for equality.
*
- * This is in contrast to { link Icon.equal}, which returns `false` for
+ * This is in contrast to { link Icon.equal}, which returns ``false`` for
* identical icons stored in different subclasses or in different storage
* locations.
*
@@ -39,7 +39,7 @@ public class Folks.TestUtils
* @param a the first icon
* @param b the second icon
* @param size the size at which to compare the icons
- * @return `true` if the instances are equal, `false` otherwise
+ * @return ``true`` if the instances are equal, ``false`` otherwise
*/
public static async bool loadable_icons_content_equal (LoadableIcon a,
LoadableIcon b,
diff --git a/tools/inspect/inspect.vala b/tools/inspect/inspect.vala
index da9f86c..555c336 100644
--- a/tools/inspect/inspect.vala
+++ b/tools/inspect/inspect.vala
@@ -455,8 +455,8 @@ public class Folks.Inspect.Client : Object
/* Reset the readline state ready to display a new prompt. If the
* pager exited as the result of a signal, it probably didn't
- * tidy up after itself (e.g. `less` leaves a colon prompt behind
- * on the current line), so move to a new line. Doing this
+ * tidy up after itself (e.g. ``less`` leaves a colon prompt
+ * behind on the current line), so move to a new line. Doing this
* normally just looks a bit weird. */
if (Process.if_signaled (status))
{
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
