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

docs: Various small fixes and expansions of documentation

 • Various links fixed to point to class documentation rather than its
   constructor documentation (this is a quirk of Valadoc; if using
   “{@link ClassName}” inside a method of ClassName, the link will point to
   ClassName’s constructor because symbols are resolved relatively and the
   class’ constructor is called “ClassName”).
 • Various bits of documentation expanded (mostly trivially) to shut gtk-doc
   up about missing long descriptions.
 • Some Vala code attributes moved around so the documentation comments are
   correctly associated with the code. (This shouldn’t change the behaviour
   of the attributes themselves.)
 • Some trivial constructors added to classes in order to give them
   documentation.
 • Constructor for Utils added and deprecated immediately. Utils should
   become a nested namespace on the next API break, since it will only ever
   contain static methods, and thus doesn’t need to be instantiable (which
   folks will make it at the moment).
parent 9cfa94ed
......@@ -34,8 +34,10 @@ extern const string BACKEND_NAME;
internal extern static async E.SourceRegistry create_source_registry (GLib.Cancellable? cancellable = null) throws GLib.Error;
/**
* A persona store.
* It will create {@link Persona}s for each contacts on the main addressbook.
* A persona store representing a single EDS address book.
*
* The persona store will contain {@link Edsf.Persona}s for each contact in the
* address book it represents.
*/
public class Edsf.PersonaStore : Folks.PersonaStore
{
......
......@@ -28,6 +28,11 @@ using Xml;
/**
* A persona subclass which represents a single EDS contact.
*
* Each {@link Edsf.Persona} instance represents a single EDS {@link E.Contact}.
* When the contact is modified (either by this folks client, or a different
* client), the {@link Edsf.Persona} remains the same, but is assigned a new
* {@link E.Contact}. It then updates its properties from this new contact.
*/
public class Edsf.Persona : Folks.Persona,
AntiLinkable,
......@@ -75,12 +80,12 @@ public class Edsf.Persona : Folks.Persona,
"email_1", "email_2", "email_3", "email_4"
};
[Deprecated]
/**
* vCard field names for miscellaneous URIs.
*
* @since 0.6.0
*/
[Deprecated]
public static const string[] url_properties = {
"blog_url", "fburl", "homepage_url", "video_url"
};
......
......@@ -29,6 +29,7 @@ extern const string BACKEND_NAME;
/**
* A persona store which is associated with a single libsocialweb service.
*
* It will create {@link Persona}s for each of the contacts known to that
* service.
*/
......
......@@ -26,6 +26,9 @@ using SocialWebClient;
/**
* A persona subclass which represents a single libsocialweb contact.
*
* There is a one-to-one correspondence between {@link Swf.Persona}s and
* {@link SocialWebClient.Contact}s.
*/
public class Swf.Persona : Folks.Persona,
AvatarDetails,
......
......@@ -27,6 +27,12 @@ using Zeitgeist;
/**
* A persona subclass which represents a single instant messaging contact from
* Telepathy.
*
* 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
* 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.
*/
public class Tpf.Persona : Folks.Persona,
AliasDetails,
......
......@@ -23,8 +23,12 @@
using GLib;
/**
* Interface for classes which represent aliasable contacts, such as
* {@link Persona} and {@link Individual}.
* Alias for a contact.
*
* This allows representation of aliases for contacts, where the user has chosen
* their own name for the contact to better represent that contact to them. A
* typical example of this is the use of user-chosen aliases for contacts in
* instant messaging programs.
*/
public interface Folks.AliasDetails : Object
{
......
......@@ -21,9 +21,19 @@
using GLib;
/**
* A singleton persistent cache object for avatars used across backends in
* folks. Avatars may be added to the cache, and referred to by a persistent
* URI from that point onwards.
* A singleton persistent cache for avatars in folks.
*
* Avatars may be added to the cache, and referred to by a persistent
* URI from that point onwards. The avatars will be stored on disk in the user's
* XDG cache directory.
*
* The avatar cache is typically used by backends where retrieving avatars is an
* expensive operation (for example, they have to be downloaded from the network
* every time they're used).
*
* All avatars from all users of the {@link Folks.AvatarCache} are stored in the
* same namespace, so callers must ensure that the IDs they use for avatars are
* globally unique (e.g. by using the corresponding {@link Folks.Persona.uid}).
*
* @since 0.6.0
*/
......@@ -52,12 +62,12 @@ public class Folks.AvatarCache : Object
}
/**
* Create or return the singleton {@link AvatarCache} class instance.
* Create or return the singleton {@link Folks.AvatarCache} class instance.
* If the instance doesn't exist already, it will be created.
*
* This function is thread-safe.
*
* @return Singleton {@link AvatarCache} instance
* @return Singleton {@link Folks.AvatarCache} instance
* @since 0.6.0
*/
public static AvatarCache dup ()
......
......@@ -23,17 +23,21 @@
using GLib;
/**
* Interface for classes which represent contacts which have an avatar
* (pictorial representation), such as {@link Persona} and {@link Individual}.
* Avatar for a contact.
*
* This allows avatars to be associated with contacts. An avatar is a small
* image file which represents the contact, such as a photo of them.
*
* @since 0.6.0
*/
public interface Folks.AvatarDetails : Object
{
/**
* An avatar for the contact.
*
* An avatar is a small image file which represents the contact. It may be
* `null` if unset. Otherwise, the image data may be asynchronously loaded
* using the methods of the {@link GLib.LoadableIcon} implementation.
* The avatar may be `null` if unset. Otherwise, the image data may be
* asynchronously loaded using the methods of the {@link GLib.LoadableIcon}
* implementation.
*
* @since 0.6.0
*/
......
......@@ -23,8 +23,10 @@
using GLib;
/**
* This interface contains the birth date of a {@link Persona} and
* {@link Individual}
* Birthday details for a contact.
*
* This allows representation of the birth date and associated calendar event ID
* of a contact.
*
* @since 0.4.0
*/
......@@ -63,7 +65,8 @@ 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.
* If this is `null`, the birthday event is unknown. The semantics of the
* event ID are left unspecified by folks.
*
* @since 0.4.0
*/
......
......@@ -32,9 +32,10 @@ private extern void g_log (string? log_domain,
...);
/**
* Manage debug output and status reporting for all folks objects. All GLib
* debug logging calls are passed through a log handler in this class, which
* allows debug domains to be outputted according to whether they've been
* Manages debug output and status reporting for all folks objects.
*
* All GLib debug logging calls are passed through a log handler in this class,
* which allows debug domains to be outputted according to whether they've been
* enabled by being passed to {@link Debug.dup}.
*
* @since 0.5.1
......@@ -184,13 +185,13 @@ public class Folks.Debug : Object
}
/**
* Create or return the singleton {@link Debug} class instance.
* Create or return the singleton {@link Folks.Debug} class instance.
* If the instance doesn't exist already, it will be created with no debug
* domains enabled.
*
* This function is thread-safe.
*
* @return Singleton {@link Debug} instance
* @return Singleton {@link Folks.Debug} instance
* @since 0.5.1
*/
public static Debug dup ()
......@@ -216,7 +217,7 @@ public class Folks.Debug : Object
}
/**
* Create or return the singleton {@link Debug} class instance.
* Create or return the singleton {@link Folks.Debug} class instance.
* If the instance doesn't exist already, it will be created with the given
* set of debug domains enabled. Otherwise, the existing instance will have
* its set of enabled domains changed to the provided set.
......@@ -225,7 +226,7 @@ public class Folks.Debug : Object
* null to disable debug output
* @param colour_enabled Whether debug output should be coloured using
* terminal escape sequences
* @return Singleton {@link Debug} instance
* @return Singleton {@link Folks.Debug} instance
* @since 0.5.1
*/
public static Debug dup_with_flags (string? debug_flags,
......@@ -315,7 +316,7 @@ public class Folks.Debug : Object
/**
* Causes all significant objects in the library to print their current
* status to standard output, obeying the options set on this
* {@link Debug} instance for colouring and other formatting.
* {@link Folks.Debug} instance for colouring and other formatting.
*
* @since 0.5.1
*/
......
......@@ -22,8 +22,13 @@
using GLib;
/**
* Interface exposing a {@link Persona}'s or {@link Individual}'s user-defined
* status as a favourite.
* Favourite status for a contact.
*
* This allows user-defined favourite contacts to be specified. A contact is a
* favourite if the user has selected them as such; the semantics of 'favourite'
* are left unspecified by folks. Typically, a user might select the contacts
* that they talk to most frequently as their favourite contacts in an instant
* messaging program, for example.
*/
public interface Folks.FavouriteDetails : Object
{
......
......@@ -45,7 +45,9 @@ public enum Folks.Gender
}
/**
* Interface for specifying the gender of a contact.
* Gender of a contact.
*
* This allows representation of the gender of a contact.
*
* @since 0.3.5
*/
......
......@@ -22,8 +22,12 @@ using GLib;
using Gee;
/**
* Interface for {@link Persona}s or {@link Individual}s which can be grouped
* into sets of similar objects.
* Groups for a contact.
*
* This allows contacts to be collected into user-defined groups (or categories)
* for organisational purposes. Groups are non-exclusive and non-hierarchical,
* so a single contact can be put into many groups, but groups may not
* themselves be put into groups.
*/
public interface Folks.GroupDetails : Object
{
......
......@@ -73,12 +73,12 @@ public enum Folks.TrustLevel
* persona store (see {@link IndividualAggregator.primary_store}), its property
* values will be chosen above all others. This means that any changes to
* property values made through folks (which are normally written to the primary
* store) will always be used by {@link Individual}s.
* store) will always be used by {@link Folks.Individual}s.
*
* No further guarantees are made about the order of preference used for
* choosing which property values to use for the {@link Individual}, other than
* that the order may vary between properties, but is guaranteed to be stable
* for a given property.
* choosing which property values to use for the {@link Folks.Individual}, other
* than that the order may vary between properties, but is guaranteed to be
* stable for a given property.
*/
public class Folks.Individual : Object,
AliasDetails,
......@@ -1083,7 +1083,7 @@ public class Folks.Individual : Object,
* {@link Folks.Individual.personas} property after construction.
*
* @param personas a list of {@link Persona}s to initialise the
* {@link Individual} with, or `null`
* {@link Folks.Individual} with, or `null`
* @return a new Individual
*
* @since 0.5.1
......@@ -2249,8 +2249,8 @@ 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 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.
......
......@@ -21,10 +21,11 @@
using GLib;
/**
* Object representing interaction details for an Individual or Persona.
* Interaction details are the number of calls or IM interactions with
* a {@link Persona} or an {@link Individual} as well as the the datetime of
* the last call and IM interaction.
* Interaction details of a contact.
*
* Interaction details are the number and date/time of calls or IM interactions
* with a contact, giving an idea of the recent interactions the user has had
* with that contact.
*
* @since 0.7.1
*/
......
......@@ -24,9 +24,11 @@
using GLib;
/**
* Object for a full name split in its constituent parts (given name,
* Structured name representation for human names.
*
* 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
......
......@@ -26,7 +26,8 @@ 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
......
......@@ -78,8 +78,15 @@ public enum Folks.MatchResult
}
/**
* This class provides functionality to explore a potential match between
* two individuals.
* Match calculator for pairs of individuals.
*
* This provides functionality to explore the degree of a potential match
* between two individuals. It compares the similarity of the individuals'
* properties to determine how likely it is that the individuals represent the
* same physical person.
*
* This can be used by folks clients to, for example, present suggestions of
* pairs of individuals which should be linked by the user.
*
* @since 0.5.0
*/
......@@ -107,6 +114,18 @@ public class Folks.PotentialMatch : Object
PotentialMatch.known_email_aliases.add ("webmaster");
}
/**
* Create a new PotentialMatch.
*
* @return a new PotentialMatch
*
* @since 0.5.0
*/
public PotentialMatch ()
{
base ();
}
/**
* Whether two individuals are likely to be the same person.
*
......
......@@ -25,8 +25,10 @@ using Gee;
using GLib;
/**
* This interface represents the role a {@link Persona} and {@link Individual}
* have in a given Organisation.
* Role a contact has in an organisation.
*
* This represents the role a {@link Persona} or {@link Individual} has in a
* single given organisation, such as a company.
*
* @since 0.4.0
*/
......
......@@ -21,9 +21,17 @@
using Gee;
/* TODO: This should be converted to a nested namespace, rather than a class,
* when folks next breaks API. Having it as a class means that a GType is always
* registered for it, and a C constructor function created, even though
* instantiating it is pointless as all the methods are static (and should
* remain so). */
/**
* Utility functions to simplify common patterns in Folks client code.
*
* These may be used by folks clients as well, and are part of folks' supported
* stable API.
*
* @since 0.6.0
*/
public class Folks.Utils : Object
......@@ -33,6 +41,21 @@ public class Folks.Utils : Object
return (a != "" && b != "" && a.down () == b.down ());
}
/**
* Create a new utilities object.
*
* This method is useless and should never be used. It will be removed in a
* future version in favour of making the Utils class into a nested namespace.
*
* @return a new utilities object
* @since 0.6.0
*/
[Deprecated (since = "UNRELEASED")]
public Utils ()
{
base ();
}
/**
* Check whether two multi-maps of strings to strings are equal. This performs
* a deep check for equality, checking whether both maps are of the same size,
......
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