[Galago-commits] r2799 - in trunk/libgalago: . docs/reference
docs/reference/tmpl libgalago
galago-commits at freedesktop.org
galago-commits at freedesktop.org
Wed May 17 18:28:27 PDT 2006
Author: chipx86
Date: 2006-05-17 18:28:19 -0700 (Wed, 17 May 2006)
New Revision: 2799
Modified:
trunk/libgalago/ChangeLog
trunk/libgalago/docs/reference/Makefile.am
trunk/libgalago/docs/reference/tmpl/galago-account.sgml
trunk/libgalago/docs/reference/tmpl/galago-object.sgml
trunk/libgalago/docs/reference/tmpl/galago-person.sgml
trunk/libgalago/docs/reference/tmpl/galago-presence.sgml
trunk/libgalago/docs/reference/tmpl/galago-service.sgml
trunk/libgalago/libgalago/galago-object.c
trunk/libgalago/libgalago/galago-presence.c
trunk/libgalago/libgalago/galago-service.h
Log:
Add more documentation.
Modified: trunk/libgalago/ChangeLog
===================================================================
--- trunk/libgalago/ChangeLog 2006-05-17 23:48:58 UTC (rev 2798)
+++ trunk/libgalago/ChangeLog 2006-05-18 01:28:19 UTC (rev 2799)
@@ -1,3 +1,16 @@
+Wed May 17 18:27:05 PDT 2006 Christian Hammond <chipx86 at chipx86.com>
+
+ * docs/reference/tmpl/galago-account.sgml:
+ * docs/reference/tmpl/galago-object.sgml:
+ * docs/reference/tmpl/galago-person.sgml:
+ * docs/reference/tmpl/galago-presence.sgml:
+ * docs/reference/tmpl/galago-service.sgml:
+ * docs/reference/Makefile.am:
+ * libgalago/galago-object.c:
+ * libgalago/galago-presence.c:
+ * libgalago/galago-service.h:
+ - Add more documentation.
+
Wed May 17 16:48:19 PDT 2006 Christian Hammond <chipx86 at chipx86.com>
* Makefile.am:
Modified: trunk/libgalago/docs/reference/Makefile.am
===================================================================
--- trunk/libgalago/docs/reference/Makefile.am 2006-05-17 23:48:58 UTC (rev 2798)
+++ trunk/libgalago/docs/reference/Makefile.am 2006-05-18 01:28:19 UTC (rev 2799)
@@ -51,6 +51,7 @@
galago-context-priv.h \
galago-enum-types.h \
galago-marshal.h \
+ galago-private.h \
galago.h
# Images to copy into HTML directory.
Modified: trunk/libgalago/docs/reference/tmpl/galago-account.sgml
===================================================================
--- trunk/libgalago/docs/reference/tmpl/galago-account.sgml 2006-05-17 23:48:58 UTC (rev 2798)
+++ trunk/libgalago/docs/reference/tmpl/galago-account.sgml 2006-05-18 01:28:19 UTC (rev 2799)
@@ -2,12 +2,19 @@
GalagoAccount
<!-- ##### SECTION Short_Description ##### -->
+An account on a messaging service.
-
<!-- ##### SECTION Long_Description ##### -->
<para>
-Account
+The #GalagoAccount object represents an account on a messaging or VoIP service,
+The account may belong to the local user, or someone on the user's contact
+list.
</para>
+<para>
+Each #GalagoAccount is owned and managed by a #GalagoService, and has
+an associated #GalagoPerson. To create a #GalagoAccount, use
+galago_service_create_account().
+</para>
<!-- ##### SECTION See_Also ##### -->
<para>
@@ -19,13 +26,14 @@
<!-- ##### STRUCT GalagoAccountPrivate ##### -->
<para>
-
+Private data belonging to a person.
</para>
<!-- ##### STRUCT GalagoAccount ##### -->
<para>
-
+This is an opaque structure representing an account. This should be used
+directly. Use the accessor functions below.
</para>
@@ -119,7 +127,7 @@
<!-- ##### MACRO GALAGO_DBUS_ACCOUNT_INTERFACE ##### -->
<para>
-
+The D-BUS interface that #GalagoAccount maps to.
</para>
Modified: trunk/libgalago/docs/reference/tmpl/galago-object.sgml
===================================================================
--- trunk/libgalago/docs/reference/tmpl/galago-object.sgml 2006-05-17 23:48:58 UTC (rev 2798)
+++ trunk/libgalago/docs/reference/tmpl/galago-object.sgml 2006-05-18 01:28:19 UTC (rev 2799)
@@ -8,7 +8,8 @@
<para>
#GalagoObject is the base class for all Galago objects. Most #GalagoObject
subclasses can be passed around in D-BUS messages through
-galago_dbus_message_append_object() and galago_dbus_message_get_object().
+galago_dbus_message_iter_append_object() and
+galago_dbus_message_iter_get_object().
</para>
<para>
#GalagoObject<!-- -->s may also support remote attributes. Examples of
@@ -76,11 +77,11 @@
Object flags.
</para>
- at GALAGO_OBJECT_IN_DESTRUCTION:
+ at GALAGO_OBJECT_IN_DESTRUCTION:
The object is currently being destroyed. This is used internally.
- at GALAGO_OBJECT_RESERVED_1:
+ at GALAGO_OBJECT_RESERVED_1:
Reserved for future use.
- at GALAGO_OBJECT_RESERVED_2:
+ at GALAGO_OBJECT_RESERVED_2:
Reserved for future use.
<!-- ##### MACRO GALAGO_OBJECT_HAS_FLAG ##### -->
@@ -138,8 +139,8 @@
<!-- ##### MACRO GALAGO_OBJECT_IS_LOCAL ##### -->
<para>
-Returns TRUE if an object is local. This is the same as comparing
-the result of galago_object_get_origin() to GALAGO_LOCAL.
+Returns %TRUE if an object is local. This is the same as comparing
+the result of galago_object_get_origin() to %GALAGO_LOCAL.
</para>
@obj: The #GalagoObject.
@@ -147,8 +148,8 @@
<!-- ##### MACRO GALAGO_OBJECT_IS_REMOTE ##### -->
<para>
-Returns TRUE if an object is remote. This is the same as comparing
-the result of galago_object_get_origin() to GALAGO_REMOTE.
+Returns %TRUE if an object is remote. This is the same as comparing
+the result of galago_object_get_origin() to %GALAGO_REMOTE.
</para>
@obj: The #GalagoObject.
Modified: trunk/libgalago/docs/reference/tmpl/galago-person.sgml
===================================================================
--- trunk/libgalago/docs/reference/tmpl/galago-person.sgml 2006-05-17 23:48:58 UTC (rev 2798)
+++ trunk/libgalago/docs/reference/tmpl/galago-person.sgml 2006-05-18 01:28:19 UTC (rev 2799)
@@ -2,16 +2,26 @@
GalagoPerson
<!-- ##### SECTION Short_Description ##### -->
+A representation of a person.
-
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+#GalagoPerson objects represent an individual user, usually one that owns
+one or more #GalagoAccount<!-- -->s. This is really a fancy container object.
</para>
+<para>
+Not all #GalagoPerson<!-- -->s map to a real person. A #GalagoPerson may have
+a unique ID provided by a feed, in which case it probably does represent a
+real person in an addressbook. However, it may be ID-less, in which case it's
+pretty much just a container.
+</para>
+<para>
+#GalagoPerson<!-- -->s are created through galago_create_person().
+</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+#GalagoAccount
</para>
<!-- ##### SECTION Stability_Level ##### -->
@@ -19,13 +29,14 @@
<!-- ##### STRUCT GalagoPersonPrivate ##### -->
<para>
-
+Private data belonging to a #GalagoPerson.
</para>
<!-- ##### STRUCT GalagoPerson ##### -->
<para>
-
+This is an opaque structure representing a person. This should be used
+directly. Use the accessor functions below.
</para>
@@ -70,70 +81,70 @@
<!-- ##### MACRO GALAGO_DBUS_PERSON_INTERFACE ##### -->
<para>
-
+The D-BUS interface that #GalagoPerson maps to.
</para>
<!-- ##### MACRO GALAGO_PERSON_ATTR_UID ##### -->
<para>
-
+A unique ID attribute.
</para>
<!-- ##### MACRO GALAGO_PERSON_ATTR_FIRST_NAME ##### -->
<para>
-
+A first name attribute.
</para>
<!-- ##### MACRO GALAGO_PERSON_ATTR_MIDDLE_NAME ##### -->
<para>
-
+A middle name attribute.
</para>
<!-- ##### MACRO GALAGO_PERSON_ATTR_LAST_NAME ##### -->
<para>
-
+A last name attribute.
</para>
<!-- ##### MACRO GALAGO_PERSON_ATTR_ADDRESS ##### -->
<para>
-
+A street address attribute.
</para>
<!-- ##### MACRO GALAGO_PERSON_ATTR_CITY ##### -->
<para>
-
+A city attribute.
</para>
<!-- ##### MACRO GALAGO_PERSON_ATTR_STATE ##### -->
<para>
-
+A state attribute.
</para>
<!-- ##### MACRO GALAGO_PERSON_ATTR_COUNTRY ##### -->
<para>
-
+A country attribute.
</para>
<!-- ##### MACRO GALAGO_PERSON_ATTR_ZIPCODE ##### -->
<para>
-
+A zipcode attribute.
</para>
Modified: trunk/libgalago/docs/reference/tmpl/galago-presence.sgml
===================================================================
--- trunk/libgalago/docs/reference/tmpl/galago-presence.sgml 2006-05-17 23:48:58 UTC (rev 2798)
+++ trunk/libgalago/docs/reference/tmpl/galago-presence.sgml 2006-05-18 01:28:19 UTC (rev 2799)
@@ -2,11 +2,12 @@
GalagoPresence
<!-- ##### SECTION Short_Description ##### -->
+An account's presence.
-
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+#GalagoPresence contains information on a #GalagoAccount<!-- -->'s presence,
+including idle time and a list of statuses.
</para>
<!-- ##### SECTION See_Also ##### -->
@@ -19,13 +20,14 @@
<!-- ##### STRUCT GalagoPresencePrivate ##### -->
<para>
-
+Private data belonging to a #GalagoPresence.
</para>
<!-- ##### STRUCT GalagoPresence ##### -->
<para>
-
+This is an opaque structure representing a presence. This should be used
+directly. Use the accessor functions below.
</para>
Modified: trunk/libgalago/docs/reference/tmpl/galago-service.sgml
===================================================================
--- trunk/libgalago/docs/reference/tmpl/galago-service.sgml 2006-05-17 23:48:58 UTC (rev 2798)
+++ trunk/libgalago/docs/reference/tmpl/galago-service.sgml 2006-05-18 01:28:19 UTC (rev 2799)
@@ -2,16 +2,26 @@
GalagoService
<!-- ##### SECTION Short_Description ##### -->
+A messaging or VoIP service.
-
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+#GalagoService represents a service of some kind, typically used for
+messaging or VoIP. It owns a list of #GalagoAccount<!-- -->s, and contains
+rules determining how account usernames should be normalized and compared.
</para>
+<para>
+#GalagoService<!-- -->s are created through galago_create_service().
+</para>
+<para>
+By default, account usernames are converted to lowercase and all spaces
+are removed when normalizing them for comparison. #GalagoServiceFlags can
+change this behavior.
+</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+#GalagoAccount
</para>
<!-- ##### SECTION Stability_Level ##### -->
@@ -19,22 +29,29 @@
<!-- ##### STRUCT GalagoServicePrivate ##### -->
<para>
-
+Private data belonging to a #GalagoAccount.
</para>
<!-- ##### ENUM GalagoServiceFlags ##### -->
<para>
-
+A list of flags specifying rules for the service. Currently this consists
+of flags dictating how account usernames should be normalized when comparing
+the usernames.
</para>
@GALAGO_PRESERVE_SPACES:
+ Preserve spaces in the account usernames when normalizing.
@GALAGO_PRESERVE_CASE:
+ Preserve casing in the account usernames when normalizing.
@GALAGO_STRIP_SLASH:
+ Strip the first slash and everything after it in the account usernames
+ when normalizing. This is used for services such as Jabber.
<!-- ##### STRUCT GalagoService ##### -->
<para>
-
+This is an opaque structure representing a service. This should be used
+directly. Use the accessor functions below.
</para>
@@ -71,91 +88,91 @@
<!-- ##### MACRO GALAGO_DBUS_SERVICE_INTERFACE ##### -->
<para>
-
+The D-BUS interface that #GalagoService maps to.
</para>
<!-- ##### MACRO GALAGO_SERVICE_ID_AIM ##### -->
<para>
-
+AOL Instant Messenger.
</para>
<!-- ##### MACRO GALAGO_SERVICE_ID_GADUGADU ##### -->
<para>
-
+Gadu-Gadu.
</para>
<!-- ##### MACRO GALAGO_SERVICE_ID_GROUPWISE ##### -->
<para>
-
+Novell GroupWise.
</para>
<!-- ##### MACRO GALAGO_SERVICE_ID_ICQ ##### -->
<para>
-
+ICQ.
</para>
<!-- ##### MACRO GALAGO_SERVICE_ID_IRC ##### -->
<para>
-
+Internet Relay Chat.
</para>
<!-- ##### MACRO GALAGO_SERVICE_ID_JABBER ##### -->
<para>
-
+Jabber.
</para>
<!-- ##### MACRO GALAGO_SERVICE_ID_MSN ##### -->
<para>
-
+MSN Messenger.
</para>
<!-- ##### MACRO GALAGO_SERVICE_ID_NAPSTER ##### -->
<para>
-
+Napster Chat.
</para>
<!-- ##### MACRO GALAGO_SERVICE_ID_SILC ##### -->
<para>
-
+Secure Internet Live Conferencing.
</para>
<!-- ##### MACRO GALAGO_SERVICE_ID_TREPIA ##### -->
<para>
-
+Trepia Instant Messenger.
</para>
<!-- ##### MACRO GALAGO_SERVICE_ID_YAHOO ##### -->
<para>
-
+Yahoo! Messenger.
</para>
<!-- ##### MACRO GALAGO_SERVICE_ID_ZEPHYR ##### -->
<para>
-
+Zephyr.
</para>
Modified: trunk/libgalago/libgalago/galago-object.c
===================================================================
--- trunk/libgalago/libgalago/galago-object.c 2006-05-17 23:48:58 UTC (rev 2798)
+++ trunk/libgalago/libgalago/galago-object.c 2006-05-18 01:28:19 UTC (rev 2799)
@@ -377,7 +377,7 @@
/**
* galago_object_set_watch
* @object: The object.
- * @watch: TRUE if this object should be watched, or FALSE.
+ * @watch: %TRUE if this object should be watched, or %FALSE.
*
* Sets whether or not this object is watched for events.
*/
@@ -398,7 +398,7 @@
*
* Returns whether or not an object is watched for events.
*
- * Returns: TRUE if this object is being watched, or FALSE.
+ * Returns: %TRUE if this object is being watched, or %FALSE.
*/
gboolean
galago_object_is_watched(const GalagoObject *object)
@@ -653,7 +653,7 @@
*
* Removes an attribute on an object.
*
- * Returns: TRUE if the attribute was removed, or FALSE.
+ * Returns: %TRUE if the attribute was removed, or %FALSE.
*/
gboolean
galago_object_remove_attribute(GalagoObject *object, const char *name)
@@ -834,7 +834,7 @@
*
* Returns whether or not an object has a specific attribute set.
*
- * Returns: TRUE if the attribute is set, or FALSE.
+ * Returns: %TRUE if the attribute is set, or %FALSE.
*/
gboolean
galago_object_get_has_attribute(const GalagoObject *object, const char *name)
Modified: trunk/libgalago/libgalago/galago-presence.c
===================================================================
--- trunk/libgalago/libgalago/galago-presence.c 2006-05-17 23:48:58 UTC (rev 2798)
+++ trunk/libgalago/libgalago/galago-presence.c 2006-05-18 01:28:19 UTC (rev 2799)
@@ -353,7 +353,7 @@
/**
* galago_presence_set_idle
* @presence: The presence.
- * @idle: TRUE if the user is idle, otherwise FALSE.
+ * @idle: %TRUE if the user is idle, otherwise %FALSE.
* @idle_start_time: The idle start time in seconds.
*
* Sets the idle start time on a presence.
@@ -471,7 +471,7 @@
* A discarded presence signifies that all existing presence info for
* that user is to be discarded.
*
- * Returns: TRUE if the presence is discarded, or FALSE.
+ * Returns: %TRUE if the presence is discarded, or %FALSE.
*/
gboolean
galago_presence_is_discarded(const GalagoPresence *presence)
@@ -488,7 +488,7 @@
*
* Returns whether or not a presence is considered available.
*
- * Returns: TRUE if the presence is available, or FALSE.
+ * Returns: %TRUE if the presence is available, or %FALSE.
*/
gboolean
galago_presence_is_available(const GalagoPresence *presence)
@@ -758,7 +758,7 @@
* Returns whether or not the status with the specified ID in a presence
* is exclusive.
*
- * Returns: TRUE if the status is exclusive, or FALSE.
+ * Returns: %TRUE if the status is exclusive, or %FALSE.
*/
gboolean
galago_presence_is_status_exclusive(const GalagoPresence *presence,
@@ -817,7 +817,7 @@
*
* Returns whether or not a presence has a status with the specified ID.
*
- * Returns: TRUE if the presence has the status, or FALSE.
+ * Returns: %TRUE if the presence has the status, or %FALSE.
*/
gboolean
galago_presence_has_status(const GalagoPresence *presence,
@@ -839,7 +839,7 @@
* Returns whether or not a presence has a status with the specified
* primitive type.
*
- * Returns: TRUE if the presence has the status, or FALSE.
+ * Returns: %TRUE if the presence has the status, or %FALSE.
*/
gboolean
galago_presence_has_status_type(const GalagoPresence *presence,
@@ -871,9 +871,9 @@
*
* Compares two presences for availability.
*
- * Returns: -1 if presence1 is less available than presence2,
- * 0 if presence1 is as available as presence2, and
- * 1 if presence1 is more available than presence2.
+ * Returns: -1 if @presence1 is less available than @presence2,
+ * 0 if @presence1 is as available as @presence2, and
+ * 1 if @presence1 is more available than @presence2.
*/
int
galago_presence_compare(const GalagoPresence *presence1,
Modified: trunk/libgalago/libgalago/galago-service.h
===================================================================
--- trunk/libgalago/libgalago/galago-service.h 2006-05-17 23:48:58 UTC (rev 2798)
+++ trunk/libgalago/libgalago/galago-service.h 2006-05-18 01:28:19 UTC (rev 2799)
@@ -32,13 +32,13 @@
typedef enum
{
- /** Preserve spaces during normalization */
+ /* Preserve spaces during normalization */
GALAGO_PRESERVE_SPACES = 1 << 0,
- /** Preserve case during normalization */
+ /* Preserve case during normalization */
GALAGO_PRESERVE_CASE = 1 << 1,
- /** Strip a slash and everything after it during normalization. */
+ /* Strip a slash and everything after it during normalization. */
GALAGO_STRIP_SLASH = 1 << 2
} GalagoServiceFlags;
More information about the galago-commits
mailing list