Commit d2d8ceb2 authored by Philip Withnall's avatar Philip Withnall
Browse files

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
parent c9f16d29
......@@ -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)
......
......@@ -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
......
......@@ -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
*/
......
......@@ -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)
*
......
......@@ -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)
{
......
......@@ -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
......
......@@ -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
*/
......
......@@ -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
*/
......
......@@ -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
*/
......
......@@ -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)
......
......@@ -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
......
......@@ -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,
......
......@@ -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
*
......
......@@ -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; }
......
......@@ -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
......
......@@ -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
*/
......
......@@ -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
*/
......
......@@ -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
*/
......
......@@ -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
*/
......
......@@ -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
*/
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment