* 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.
*
/**
* 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)
/**
* 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
/**
* 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)
* 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
*/
* 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
*/
* 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)
{
/**
* 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)
*
/**
* 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)
{
* 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
/**
* 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
* 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
*/
*
* 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
*/
* 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
*/
*
* 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
*
* 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
*/
*
* 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.
*/
/**
* 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
/**
* 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
}
/**
- * 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.
* @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
* 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)
/**
* 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)
* 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
/**
* 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,
* 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
* 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
/**
* 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
/**
* 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
/**
* 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
*
* 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; }
* 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.
/**
* 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)
/**
* 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
/**
* 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
* 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
*/
/**
* 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.
*
* 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
*/
/**
* 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
*/
* 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
*/
* {@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
*/
* 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
*/
* 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
*/
/**
* 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
* 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
*/
* @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
*
* 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
*/
/**
* 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
* @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
*
* 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
*/
* 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
*/
* 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
* 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.
* @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
* @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
*/
/* 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.
*/
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> ();
}
/**
- * 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
* * 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
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,
* {@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
* {@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”)
* @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
/**
* 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
* 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
* 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
*/
*
* 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
*/
* 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);
/**
* 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)]
/**
* 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.
* 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
* 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)
/**
* 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
*/
* 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)
*
* 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
/**
* 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
*
* 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
/**
* 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
* 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
* 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
* 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
*/
* 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
*/
* 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
* @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
* 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
*/
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
/**
* 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,
/**
* 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
*/
* 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
*/
/**
* 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
*/
/**
* 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
*/
* 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
*/
* 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
* 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
*/
* 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.
*
* 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
* 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
* 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
* 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
*/
/**
* 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.
*
*
* 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.
*
* 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}.
* @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
*
*
* 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
*/
/**
* 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
/**
* 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
/**
* 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
/**
* 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)
{
*
* @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
* 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
/**
* 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
/**
* 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 ()
{
/**
* 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
*
* @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)
{
*
* @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
*
* @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
*
*
* @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
*/
*
* @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
*/
*
* @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
*/
*
* @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
*
/**
* 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.
*
* @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,
/* 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))
{