[Galago-commits] r2351 - in trunk/libgalago: . libgalago
galago-commits at freedesktop.org
galago-commits at freedesktop.org
Fri Dec 2 01:39:24 PST 2005
Author: chipx86
Date: 2005-12-02 01:39:16 -0800 (Fri, 02 Dec 2005)
New Revision: 2351
Modified:
trunk/libgalago/ChangeLog
trunk/libgalago/Doxyfile.in
trunk/libgalago/libgalago/galago-account.h
trunk/libgalago/libgalago/galago-assert.h
trunk/libgalago/libgalago/galago-context-base.h
trunk/libgalago/libgalago/galago-context-priv.h
trunk/libgalago/libgalago/galago-context.h
trunk/libgalago/libgalago/galago-core.h
trunk/libgalago/libgalago/galago-dbus.h
trunk/libgalago/libgalago/galago-image.h
trunk/libgalago/libgalago/galago-object.h
trunk/libgalago/libgalago/galago-person.h
trunk/libgalago/libgalago/galago-presence.h
trunk/libgalago/libgalago/galago-private.h
trunk/libgalago/libgalago/galago-service.h
trunk/libgalago/libgalago/galago-status.h
trunk/libgalago/libgalago/galago-value.h
trunk/libgalago/libgalago/galago.h
Log:
Patch by Ross Burton to fix up the documentation for Doxygen, and to add to it a bit.
Modified: trunk/libgalago/ChangeLog
===================================================================
--- trunk/libgalago/ChangeLog 2005-11-28 05:18:00 UTC (rev 2350)
+++ trunk/libgalago/ChangeLog 2005-12-02 09:39:16 UTC (rev 2351)
@@ -1,3 +1,25 @@
+Fri Dec 02 01:38:32 PST 2005 Christian Hammond <chipx86 at chipx86.com>
+
+ * libgalago/galago-account.h:
+ * libgalago/galago-assert.h:
+ * libgalago/galago-context-base.h:
+ * libgalago/galago-context.h:
+ * libgalago/galago-context-priv.h:
+ * libgalago/galago-core.h:
+ * libgalago/galago-dbus.h:
+ * libgalago/galago-image.h:
+ * libgalago/galago-object.h:
+ * libgalago/galago-person.h:
+ * libgalago/galago-presence.h:
+ * libgalago/galago-private.h:
+ * libgalago/galago-service.h:
+ * libgalago/galago-status.h:
+ * libgalago/galago-value.h:
+ * libgalago/galago.h:
+ * Doxyfile.in:
+ - Patch by Ross Burton to fix up the documentation for Doxygen, and to
+ add to it a bit.
+
Sun Nov 27 15:17:27 PST 2005 Christian Hammond <chipx86 at chipx86.com>
* libgalago/Makefile.am:
Modified: trunk/libgalago/Doxyfile.in
===================================================================
--- trunk/libgalago/Doxyfile.in 2005-11-28 05:18:00 UTC (rev 2350)
+++ trunk/libgalago/Doxyfile.in 2005-12-02 09:39:16 UTC (rev 2351)
@@ -232,7 +232,7 @@
# to NO (the default) then the documentation will be excluded.
# Set it to YES to include the internal documentation.
-INTERNAL_DOCS = NO
+INTERNAL_DOCS = YES
# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate
# file names in lower-case letters. If set to YES upper-case letters are also
Modified: trunk/libgalago/libgalago/galago-account.h
===================================================================
--- trunk/libgalago/libgalago/galago-account.h 2005-11-28 05:18:00 UTC (rev 2350)
+++ trunk/libgalago/libgalago/galago-account.h 2005-12-02 09:39:16 UTC (rev 2351)
@@ -1,6 +1,10 @@
/**
* @file libgalago/galago-account.h Galago Account API
+ * @ingroup Presence
*
+ * #GalagoAccount models a single account a #GalagoPerson has with a
+ * provider (a #GalagoService).
+ *
* @Copyright (C) 2004-2005 Christian Hammond
*
* This library is free software; you can redistribute it and/or
@@ -40,10 +44,12 @@
GalagoAccountPrivate *priv;
+#ifndef _DOXYGEN_
void (*reserved_1)(void);
void (*reserved_2)(void);
void (*reserved_3)(void);
void (*reserved_4)(void);
+#endif
};
/**
@@ -61,23 +67,38 @@
void (*contact_added)(GalagoAccount *account, GalagoAccount *contact);
void (*contact_removed)(GalagoAccount *account, GalagoAccount *contact);
+#ifndef _DOXYGEN_
void (*reserved_1)(void);
void (*reserved_2)(void);
void (*reserved_3)(void);
void (*reserved_4)(void);
+#endif
};
#define GALAGO_TYPE_ACCOUNT (galago_account_get_type())
+
+/** Cast @c obj to a GalagoAccount. */
#define GALAGO_ACCOUNT(obj) \
- (G_TYPE_CHECK_INSTANCE_CAST((obj), GALAGO_TYPE_ACCOUNT, GalagoAccount))
+ (G_TYPE_CHECK_INSTANCE_CAST((obj), GALAGO_TYPE_ACCOUNT, \
+ GalagoAccount))
+
+/** Cast @c klass to a GalagoAccount. */
#define GALAGO_ACCOUNT_CLASS(klass) \
- (G_TYPE_CHECK_CLASS_CAST((klass), GALAGO_TYPE_ACCOUNT, GalagoAccountClass))
+ (G_TYPE_CHECK_CLASS_CAST((klass), GALAGO_TYPE_ACCOUNT, \
+ GalagoAccountClass))
+
+/** Check if @c obj is a GalagoAccount. */
#define GALAGO_IS_ACCOUNT(obj) \
(G_TYPE_CHECK_INSTANCE_TYPE((obj), GALAGO_TYPE_ACCOUNT))
+
+/** Check if @c klass is a GalagoAccountClass. */
#define GALAGO_IS_ACCOUNT_CLASS(klass) \
(G_TYPE_CHECK_CLASS_TYPE((klass), GALAGO_TYPE_ACCOUNT))
+
+/** Get the class for the GalagoAccount @c obj. */
#define GALAGO_ACCOUNT_GET_CLASS(obj) \
- (G_TYPE_INSTANCE_GET_CLASS((obj), GALAGO_TYPE_ACCOUNT, GalagoAccountClass))
+ (G_TYPE_INSTANCE_GET_CLASS((obj), GALAGO_TYPE_ACCOUNT, \
+ GalagoAccountClass))
#define GALAGO_DBUS_ACCOUNT_INTERFACE "org.freedesktop.Galago.Account"
@@ -116,7 +137,7 @@
/**
* Sets the account's person.
*
- * This is used internally. You don't need to call this.
+ * @internal This is used internally.
*
* @param account The account.
* @param person The account's person.
@@ -235,7 +256,7 @@
/**
* Sets the account's presence.
*
- * This is used internally. You don't need to call this.
+ * @internal This is used internally.
*
* @param account The account.
* @param presence The presence to set.
Modified: trunk/libgalago/libgalago/galago-assert.h
===================================================================
--- trunk/libgalago/libgalago/galago-assert.h 2005-11-28 05:18:00 UTC (rev 2350)
+++ trunk/libgalago/libgalago/galago-assert.h 2005-12-02 09:39:16 UTC (rev 2351)
@@ -1,5 +1,6 @@
/**
* @file libgalago/galago-assert.h Assertion API
+ * @ingroup Utility
*
* @Copyright (C) 2004-2005 Christian Hammond.
*
Modified: trunk/libgalago/libgalago/galago-context-base.h
===================================================================
--- trunk/libgalago/libgalago/galago-context-base.h 2005-11-28 05:18:00 UTC (rev 2350)
+++ trunk/libgalago/libgalago/galago-context-base.h 2005-12-02 09:39:16 UTC (rev 2351)
@@ -1,5 +1,6 @@
/**
* @file libgalago/galago-context-base.h Galago Context Base Support
+ * @ingroup Presence
*
* @Copyright (C) 2004-2005 Christian Hammond
*
@@ -27,38 +28,63 @@
#include <libgalago/galago-object.h>
+/**
+ * The current context.
+ *
+ * The context contains the state of the current Galago connection.
+ */
struct _GalagoContext
{
GalagoObject parent_object;
GalagoContextPrivate *priv;
+#ifndef _DOXYGEN_
void (*reserved_1)(void);
void (*reserved_2)(void);
void (*reserved_3)(void);
void (*reserved_4)(void);
+#endif
};
+/**
+ * GalagoContext's class.
+ */
struct _GalagoContextClass
{
GalagoObjectClass parent_class;
+#ifndef _DOXYGEN_
void (*reserved_1)(void);
void (*reserved_2)(void);
void (*reserved_3)(void);
void (*reserved_4)(void);
+#endif
};
#define GALAGO_TYPE_CONTEXT (galago_context_get_type())
+
+/** Cast @c obj to a GalagoContext. */
#define GALAGO_CONTEXT(obj) \
- (G_TYPE_CHECK_INSTANCE_CAST((obj), GALAGO_TYPE_CONTEXT, GalagoContext))
+ (G_TYPE_CHECK_INSTANCE_CAST((obj), GALAGO_TYPE_CONTEXT, \
+ GalagoContext))
+
+/** Cast @c klass to a GalagoContextClass. */
#define GALAGO_CONTEXT_CLASS(klass) \
- (G_TYPE_CHECK_CLASS_CAST((klass), GALAGO_TYPE_CONTEXT, GalagoContextClass))
+ (G_TYPE_CHECK_CLASS_CAST((klass), GALAGO_TYPE_CONTEXT, \
+ GalagoContextClass))
+
+/** Check if @c obj is a GalagoContext. */
#define GALAGO_IS_CONTEXT(obj) \
(G_TYPE_CHECK_INSTANCE_TYPE((obj), GALAGO_TYPE_CONTEXT))
+
+/** Check if @c klass is a GalagoContextClass. */
#define GALAGO_IS_CONTEXT_CLASS(klass) \
(G_TYPE_CHECK_CLASS_TYPE((klass), GALAGO_TYPE_CONTEXT))
+
+/** Get the class for the GalagoContext @c obj. */
#define GALAGO_CONTEXT_GET_CLASS(obj) \
- (G_TYPE_INSTANCE_GET_CLASS((obj), GALAGO_TYPE_CONTEXT, GalagoContextClass))
+ (G_TYPE_INSTANCE_GET_CLASS((obj), GALAGO_TYPE_CONTEXT, \
+ GalagoContextClass))
#endif /* _GALAGO_CONTEXT_BASE_H_ */
Modified: trunk/libgalago/libgalago/galago-context-priv.h
===================================================================
--- trunk/libgalago/libgalago/galago-context-priv.h 2005-11-28 05:18:00 UTC (rev 2350)
+++ trunk/libgalago/libgalago/galago-context-priv.h 2005-12-02 09:39:16 UTC (rev 2351)
@@ -1,5 +1,6 @@
/**
* @file libgalago/galago-context-priv.h Galago Context Private API
+ * @ingroup Presence
*
* @Copyright (C) 2004-2005 Christian Hammond
*
@@ -26,11 +27,18 @@
#include <libgalago/galago-person.h>
#include <libgalago/galago-service.h>
+/**
+ * The context operations.
+ */
struct _GalagoContextOps
{
+ /** Called when a service is added. */
void (*service_added)(GalagoService *service);
+ /** Called when a service is removed. */
void (*service_removed)(GalagoService *service);
+ /** Called when a person is added. */
void (*person_added)(GalagoPerson *person);
+ /** Called when a person is removed. */
void (*person_removed)(GalagoPerson *person);
};
@@ -80,7 +88,7 @@
/**
* Adds an object to the internal object tree.
*
- * This should only be used internally.
+ * @internal This is used internally.
*
* @param obj The object to add.
*/
@@ -89,7 +97,7 @@
/**
* Removes an object from the internal object tree.
*
- * This should only be used internally.
+ * @internal This is used internally.
*
* @param obj The object to remove.
*/
@@ -98,7 +106,7 @@
/**
* Clears all objects of a specified origin from a context.
*
- * This should only be used internally.
+ * @internal This is used internally.
*
* @param origin The origin of objects to clear.
*/
Modified: trunk/libgalago/libgalago/galago-context.h
===================================================================
--- trunk/libgalago/libgalago/galago-context.h 2005-11-28 05:18:00 UTC (rev 2350)
+++ trunk/libgalago/libgalago/galago-context.h 2005-12-02 09:39:16 UTC (rev 2351)
@@ -1,5 +1,6 @@
/**
* @file libgalago/galago-context.h Galago Context API
+ * @ingroup Presence
*
* @Copyright (C) 2004-2005 Christian Hammond
*
Modified: trunk/libgalago/libgalago/galago-core.h
===================================================================
--- trunk/libgalago/libgalago/galago-core.h 2005-11-28 05:18:00 UTC (rev 2350)
+++ trunk/libgalago/libgalago/galago-core.h 2005-12-02 09:39:16 UTC (rev 2351)
@@ -1,5 +1,6 @@
/**
- * @file libgalago/galago-core.h Galago Context API
+ * @file libgalago/galago-core.h Galago Core API
+ * @ingroup Presence
*
* @Copyright (C) 2004-2005 Christian Hammond
*
@@ -34,6 +35,10 @@
G_BEGIN_DECLS
+/**************************************************************************/
+/** @name Core API */
+/**************************************************************************/
+
/**
* Initializes Galago.
*
@@ -98,8 +103,7 @@
/**
* Returns the local Galago connection's unique ID.
*
- * This ID is used in D-BUS object paths. It's really only needed
- * internally.
+ * @internal This ID is used in D-BUS object paths.
*
* @return This connection's unique ID.
*/
@@ -226,7 +230,7 @@
/**
* Adds a person to Galago's person cache.
*
- * This is used internally. You don't need to call this.
+ * @internal This is used internally.
*
* @param person The person to add.
*/
@@ -235,7 +239,7 @@
/**
* Removes a person from Galago's person cache.
*
- * This is used internally. You don't need to call this.
+ * @internal This is used internally.
*
* @param person The person to remove.
*/
Modified: trunk/libgalago/libgalago/galago-dbus.h
===================================================================
--- trunk/libgalago/libgalago/galago-dbus.h 2005-11-28 05:18:00 UTC (rev 2350)
+++ trunk/libgalago/libgalago/galago-dbus.h 2005-12-02 09:39:16 UTC (rev 2351)
@@ -1,5 +1,6 @@
/**
* @file libgalago/galago-dbus.h D-BUS Support API
+ * @ingroup Utility
*
* @Copyright (C) 2004-2005 Christian Hammond.
*
@@ -21,7 +22,9 @@
#ifndef _GALAGO_DBUS_H_
#define _GALAGO_DBUS_H_
+#ifndef _DOXYGEN_
#define DBUS_API_SUBJECT_TO_CHANGE
+#endif
#include <dbus/dbus.h>
#include <libgalago/galago-object.h>
@@ -34,9 +37,10 @@
G_BEGIN_DECLS
-/**************************************************************************
- * Utility functions
- **************************************************************************/
+/**************************************************************************/
+/** @name Utility functions */
+/**************************************************************************/
+/*@{*/
/**
* Appends a string to a message, or an empty string if the passed string
@@ -123,7 +127,7 @@
* @param object The object.
* @param name The message name.
* @param reply TRUE if a reply is expected.
- * @param va_list The va_list of parameters.
+ * @param args The @c va_list of parameters.
*
* @return The D-BUS message.
*/
@@ -198,7 +202,7 @@
/**
* Pushes an object and all its internal data to the server.
*
- * This should only be used internally.
+ * @internal This is used internally.
*
* @param object The object to push.
*/
@@ -214,6 +218,8 @@
*/
const char *galago_dbus_normalize_name(const char *name);
+/*@}*/
+
G_END_DECLS
#endif /* _GALAGO_DBUS_H_ */
Modified: trunk/libgalago/libgalago/galago-image.h
===================================================================
--- trunk/libgalago/libgalago/galago-image.h 2005-11-28 05:18:00 UTC (rev 2350)
+++ trunk/libgalago/libgalago/galago-image.h 2005-12-02 09:39:16 UTC (rev 2351)
@@ -1,5 +1,6 @@
/**
* @file libgalago/galago-image.h Galago Image API
+ * @ingroup Utility
*
* @Copyright (C) 2004-2005 Christian Hammond
*
@@ -29,7 +30,7 @@
#include <libgalago/galago-object.h>
-/*
+/**
* An abstract representation of an image.
*/
struct _GalagoImage
@@ -38,10 +39,12 @@
GalagoImagePrivate *priv;
+#ifndef _DOXYGEN_
void (*reserved_1)(void);
void (*reserved_2)(void);
void (*reserved_3)(void);
void (*reserved_4)(void);
+#endif
};
/**
@@ -53,21 +56,33 @@
void (*image_data_set)(GalagoImage *image);
+#ifndef _DOXYGEN_
void (*reserved_1)(void);
void (*reserved_2)(void);
void (*reserved_3)(void);
void (*reserved_4)(void);
+#endif
};
#define GALAGO_TYPE_IMAGE (galago_image_get_type())
+
+/** Cast @c obj to a GalagoImage. */
#define GALAGO_IMAGE(obj) \
(G_TYPE_CHECK_INSTANCE_CAST((obj), GALAGO_TYPE_IMAGE, GalagoImage))
+
+/** Cast @c klass to a GalagoImageClass. */
#define GALAGO_IMAGE_CLASS(klass) \
(G_TYPE_CHECK_CLASS_CAST((klass), GALAGO_TYPE_IMAGE, GalagoImageClass))
+
+/** Check if @c obj is a GalagoImage. */
#define GALAGO_IS_IMAGE(obj) \
(G_TYPE_CHECK_INSTANCE_TYPE((obj), GALAGO_TYPE_IMAGE))
+
+/** Check if @c klass is a GalagoImageClass. */
#define GALAGO_IS_IMAGE_CLASS(klass) \
(G_TYPE_CHECK_CLASS_TYPE((klass), GALAGO_TYPE_IMAGE))
+
+/** Get the class for the GalagoImage @c obj. */
#define GALAGO_IMAGE_GET_CLASS(obj) \
(G_TYPE_INSTANCE_GET_CLASS((obj), GALAGO_TYPE_IMAGE, GalagoImageClass))
Modified: trunk/libgalago/libgalago/galago-object.h
===================================================================
--- trunk/libgalago/libgalago/galago-object.h 2005-11-28 05:18:00 UTC (rev 2350)
+++ trunk/libgalago/libgalago/galago-object.h 2005-12-02 09:39:16 UTC (rev 2351)
@@ -1,5 +1,6 @@
/**
* @file libgalago/galago-object.h Galago Base Object
+ * @ingroup Utility
*
* @Copyright (C) 2004-2005 Christian Hammond
*
@@ -24,7 +25,9 @@
#include <glib.h>
#include <glib-object.h>
+#ifndef _DOXYGEN_
#define DBUS_API_SUBJECT_TO_CHANGE
+#endif
#include <dbus/dbus.h>
typedef struct _GalagoObjectClass GalagoObjectClass;
@@ -41,10 +44,12 @@
GalagoObjectPrivate *priv;
+#ifndef _DOXYGEN_
void (*reserved_1)(void);
void (*reserved_2)(void);
void (*reserved_3)(void);
void (*reserved_4)(void);
+#endif
};
/**
@@ -67,40 +72,62 @@
/* Signals */
void (*destroy)(GalagoObject *object);
+#ifndef _DOXYGEN_
void (*reserved_1)(void);
void (*reserved_2)(void);
void (*reserved_3)(void);
void (*reserved_4)(void);
+#endif
};
#define GALAGO_TYPE_OBJECT (galago_object_get_type())
+
+/** Cast @c obj to a GalagoObject. */
#define GALAGO_OBJECT(obj) \
(G_TYPE_CHECK_INSTANCE_CAST((obj), GALAGO_TYPE_OBJECT, GalagoObject))
+
+/** Cast @c klass to a GalagoObject. */
#define GALAGO_OBJECT_CLASS(klass) \
- (G_TYPE_CHECK_CLASS_CAST((klass), GALAGO_TYPE_OBJECT, GalagoObjectClass))
+ (G_TYPE_CHECK_CLASS_CAST((klass), GALAGO_TYPE_OBJECT, \
+ GalagoObjectClass))
+
+/** Check if @c obj is a GalagoObject. */
#define GALAGO_IS_OBJECT(obj) \
(G_TYPE_CHECK_INSTANCE_TYPE((obj), GALAGO_TYPE_OBJECT))
+
+/** Check if @c klass is a GalagoObjectClass. */
#define GALAGO_IS_OBJECT_CLASS(klass) \
(G_TYPE_CHECK_CLASS_TYPE((klass), GALAGO_TYPE_OBJECT))
+
+/** Get the class for the GalagoObject @c obj. */
#define GALAGO_OBJECT_GET_CLASS(obj) \
- (G_TYPE_INSTANCE_GET_CLASS((obj), GALAGO_TYPE_OBJECT, GalagoObjectClass))
+ (G_TYPE_INSTANCE_GET_CLASS((obj), GALAGO_TYPE_OBJECT, \
+ GalagoObjectClass))
/**
* Object flags.
*/
typedef enum
{
+ /** The object is currently being destroyed */
GALAGO_OBJECT_IN_DESTRUCTION = 1,
GALAGO_OBJECT_RESERVED_1 = 2,
GALAGO_OBJECT_RESERVED_2 = 4
} GalagoObjectFlags;
+/** Check if @c obj has @c flag set. */
#define GALAGO_OBJECT_HAS_FLAG(obj, flag) \
((GALAGO_OBJECT_FLAGS(obj) & (flag)) == (flag))
+
+/** Get the flags for @c obj. */
#define GALAGO_OBJECT_FLAGS(obj) (GALAGO_OBJECT(obj)->flags)
+
+/** Set the flags for @c obj whch are set in @c flags. */
#define GALAGO_OBJECT_SET_FLAGS(obj, flag) \
G_STMT_START{ (GALAGO_OBJECT_FLAGS(obj) |= (flag)); } G_STMT_END
+
+/** Unset the flags for @c obj whch are set in @c flags. */
#define GALAGO_OBJECT_UNSET_FLAGS(obj, flag) \
G_STMT_START{ (GALAGO_OBJECT_FLAGS(obj) &= ~(flag)); } G_STMT_END
Modified: trunk/libgalago/libgalago/galago-person.h
===================================================================
--- trunk/libgalago/libgalago/galago-person.h 2005-11-28 05:18:00 UTC (rev 2350)
+++ trunk/libgalago/libgalago/galago-person.h 2005-12-02 09:39:16 UTC (rev 2351)
@@ -1,6 +1,12 @@
/**
* @file libgalago/galago-person.h Galago Person API
+ * @ingroup Presence
*
+ * #GalagoPerson represents a single person and their personal information
+ * (such as name and address). As people can have multiple IM accounts, each
+ * #GalagoPerson can have many #GalagoAccount%s associated with it
+ * (created using galago_service_create_account()).
+ *
* @Copyright (C) 2004-2005 Christian Hammond
*
* This library is free software; you can redistribute it and/or
@@ -40,10 +46,12 @@
GalagoPersonPrivate *priv;
+#ifndef _DOXYGEN_
void (*reserved_1)(void);
void (*reserved_2)(void);
void (*reserved_3)(void);
void (*reserved_4)(void);
+#endif
};
/**
@@ -58,10 +66,12 @@
void (*account_removed)(GalagoPerson *person, GalagoAccount *account);
void (*photo_set)(GalagoPerson *person, GalagoImage *photo);
+#ifndef _DOXYGEN_
void (*reserved_1)(void);
void (*reserved_2)(void);
void (*reserved_3)(void);
void (*reserved_4)(void);
+#endif
};
typedef enum
@@ -74,16 +84,27 @@
} GalagoPropertyType;
#define GALAGO_TYPE_PERSON (galago_person_get_type())
+
+/** Cast @c obj to a GalagoPerson. */
#define GALAGO_PERSON(obj) \
(G_TYPE_CHECK_INSTANCE_CAST((obj), GALAGO_TYPE_PERSON, GalagoPerson))
+
+/** Cast @c klass to a GalagoPerson. */
#define GALAGO_PERSON_CLASS(klass) \
- (G_TYPE_CHECK_CLASS_CAST((klass), GALAGO_TYPE_PERSON, GalagoPersonClass))
+ (G_TYPE_CHECK_CLASS_CAST((klass), GALAGO_TYPE_PERSON, \
+ GalagoPersonClass))
+/** Check if @c obj is a GalagoPerson. */
#define GALAGO_IS_PERSON(obj) \
(G_TYPE_CHECK_INSTANCE_TYPE((obj), GALAGO_TYPE_PERSON))
+
+/** Check if @c klass is a GalagoPersonClass. */
#define GALAGO_IS_PERSON_CLASS(klass) \
(G_TYPE_CHECK_CLASS_TYPE((klass), GALAGO_TYPE_PERSON))
+
+/** Get the class for the GalagoPerson @c obj. */
#define GALAGO_PERSON_GET_CLASS(obj) \
- (G_TYPE_INSTANCE_GET_CLASS((obj), GALAGO_TYPE_PERSON, GalagoPersonClass))
+ (G_TYPE_INSTANCE_GET_CLASS((obj), GALAGO_TYPE_PERSON, \
+ GalagoPersonClass))
#define GALAGO_DBUS_PERSON_INTERFACE "org.freedesktop.Galago.Person"
@@ -121,12 +142,11 @@
/**
* Sets a person to be the "Me" person.
*
- * This should only be used internally. Please use galago_person_me_new()
- * from the beginning.
- *
* This is a one-way thing. You can't make a "Me" person a normal
* person.
*
+ * @internal Please use galago_get_me() instead of ever using this.
+ *
* @param person The person.
*/
void galago_person_set_me(GalagoPerson *person);
@@ -153,7 +173,7 @@
* Returns the display name of a person, if any.
*
* The returned display name is from a static buffer. If you wish to store
- * the name, you must g_strdup it.
+ * the name, you must @c g_strdup it.
*
* @param person The person.
*
@@ -218,7 +238,7 @@
/**
* Adds an account to a person.
*
- * This is used internally. You don't need to call this.
+ * @internal This is used internally.
*
* @param person The person.
* @param account The account to add.
@@ -228,7 +248,7 @@
/**
* Removes an account from a person.
*
- * This is used internally. You don't need to call this.
+ * @internal This is used internally.
*
* @param person The person.
* @param account The account to remove.
Modified: trunk/libgalago/libgalago/galago-presence.h
===================================================================
--- trunk/libgalago/libgalago/galago-presence.h 2005-11-28 05:18:00 UTC (rev 2350)
+++ trunk/libgalago/libgalago/galago-presence.h 2005-12-02 09:39:16 UTC (rev 2351)
@@ -1,6 +1,11 @@
/**
* @file libgalago/galago-presence.h Galago Presence API
+ * @ingroup Presence
*
+ * A presence is associated with a #GalagoAccount and contains a list of the
+ * account's statuses (#GalagoStatus), the current status, the idle time, and
+ * other information.
+ *
* @Copyright (C) 2004-2005 Christian Hammond
*
* This library is free software; you can redistribute it and/or
@@ -45,12 +50,17 @@
GalagoPresencePrivate *priv;
+#ifndef _DOXYGEN_
void (*reserved_1)(void);
void (*reserved_2)(void);
void (*reserved_3)(void);
void (*reserved_4)(void);
+#endif
};
+/**
+ * GalagoPresence's class.
+ */
struct _GalagoPresenceClass
{
GalagoObjectClass parent_class;
@@ -64,23 +74,38 @@
const char *attr_id);
void (*changed)(GalagoPresence *presence);
+#ifndef _DOXYGEN_
void (*reserved_1)(void);
void (*reserved_2)(void);
void (*reserved_3)(void);
void (*reserved_4)(void);
+#endif
};
#define GALAGO_TYPE_PRESENCE (galago_presence_get_type())
+
+/** Cast @c obj to a GalagoPresence. */
#define GALAGO_PRESENCE(obj) \
- (G_TYPE_CHECK_INSTANCE_CAST((obj), GALAGO_TYPE_PRESENCE, GalagoPresence))
+ (G_TYPE_CHECK_INSTANCE_CAST((obj), GALAGO_TYPE_PRESENCE, \
+ GalagoPresence))
+
+/** Cast @c klass to a GalagoPresenceClass. */
#define GALAGO_PRESENCE_CLASS(klass) \
- (G_TYPE_CHECK_CLASS_CAST((klass), GALAGO_TYPE_PRESENCE, GalagoPresenceClass))
+ (G_TYPE_CHECK_CLASS_CAST((klass), GALAGO_TYPE_PRESENCE, \
+ GalagoPresenceClass))
+
+/** Check if @c obj is a GalagoPresence. */
#define GALAGO_IS_PRESENCE(obj) \
(G_TYPE_CHECK_INSTANCE_TYPE((obj), GALAGO_TYPE_PRESENCE))
+
+/** Check if @c klass is a GalagoPresenceClass. */
#define GALAGO_IS_PRESENCE_CLASS(klass) \
(G_TYPE_CHECK_CLASS_TYPE((klass), GALAGO_TYPE_PRESENCE))
+
+/** Get the class for the GalagoPresence @c obj. */
#define GALAGO_PRESENCE_GET_CLASS(obj) \
- (G_TYPE_INSTANCE_GET_CLASS((obj), GALAGO_TYPE_PRESENCE, GalagoPresenceClass))
+ (G_TYPE_INSTANCE_GET_CLASS((obj), GALAGO_TYPE_PRESENCE, \
+ GalagoPresenceClass))
#define GALAGO_DBUS_PRESENCE_INTERFACE "org.freedesktop.Galago.Presence"
@@ -102,7 +127,7 @@
* Sets the idle start time on a presence.
*
* @param presence The presence.
- * @param idle TRUE if the user is idle, or FALSE.
+ * @param idle TRUE if the user is idle, otherwise FALSE.
* @param idle_time The idle start time in seconds.
*/
void galago_presence_set_idle(GalagoPresence *presence, gboolean idle,
@@ -111,7 +136,7 @@
/**
* Sets a list of statuses in a presence.
*
- * The presence claims ownership of the list and will g_free it when
+ * The presence claims ownership of the list and will free it when
* destroyed.
*
* @param presence The presence.
Modified: trunk/libgalago/libgalago/galago-private.h
===================================================================
--- trunk/libgalago/libgalago/galago-private.h 2005-11-28 05:18:00 UTC (rev 2350)
+++ trunk/libgalago/libgalago/galago-private.h 2005-12-02 09:39:16 UTC (rev 2351)
@@ -1,5 +1,6 @@
/**
* @file libgalago/galago-private.h Private declarations
+ * @ingroup Utility
*
* @Copyright (C) 2004-2005 Christian Hammond
*
Modified: trunk/libgalago/libgalago/galago-service.h
===================================================================
--- trunk/libgalago/libgalago/galago-service.h 2005-11-28 05:18:00 UTC (rev 2350)
+++ trunk/libgalago/libgalago/galago-service.h 2005-12-02 09:39:16 UTC (rev 2351)
@@ -1,6 +1,11 @@
/**
* @file libgalago/galago-service.h Galago Service API
+ * @ingroup Presence
*
+ * A #GalagoService represents an online service to which users can
+ * connect that keeps track of the user's presence. Examples are instant
+ * messaging services (such as Jabber) or video chat (such as SIP).
+ *
* @Copyright (C) 2004-2005 Christian Hammond
*
* This library is free software; you can redistribute it and/or
@@ -52,10 +57,12 @@
GalagoServicePrivate *priv;
+#ifndef _DOXYGEN_
void (*reserved_1)(void);
void (*reserved_2)(void);
void (*reserved_3)(void);
void (*reserved_4)(void);
+#endif
};
/**
@@ -69,23 +76,38 @@
void (*account_added)(GalagoService *service, GalagoAccount *account);
void (*account_removed)(GalagoService *service, GalagoAccount *account);
+#ifndef _DOXYGEN_
void (*reserved_1)(void);
void (*reserved_2)(void);
void (*reserved_3)(void);
void (*reserved_4)(void);
+#endif
};
#define GALAGO_TYPE_SERVICE (galago_service_get_type())
+
+/** Cast @c obj to a GalagoService. */
#define GALAGO_SERVICE(obj) \
- (G_TYPE_CHECK_INSTANCE_CAST((obj), GALAGO_TYPE_SERVICE, GalagoService))
+ (G_TYPE_CHECK_INSTANCE_CAST((obj), GALAGO_TYPE_SERVICE, \
+ GalagoService))
+
+/** Cast @c klass to a GalagoService. */
#define GALAGO_SERVICE_CLASS(klass) \
- (G_TYPE_CHECK_CLASS_CAST((klass), GALAGO_TYPE_SERVICE, GalagoServiceClass))
+ (G_TYPE_CHECK_CLASS_CAST((klass), GALAGO_TYPE_SERVICE, \
+ GalagoServiceClass))
+
+/** Check if @c obj is a GalagoService. */
#define GALAGO_IS_SERVICE(obj) \
(G_TYPE_CHECK_INSTANCE_TYPE((obj), GALAGO_TYPE_SERVICE))
+
+/** Check if @c klass is a GalagoServiceClass. */
#define GALAGO_IS_SERVICE_CLASS(klass) \
(G_TYPE_CHECK_CLASS_TYPE((klass), GALAGO_TYPE_SERVICE))
+
+/** Get the class for the GalagoService @c obj. */
#define GALAGO_SERVICE_GET_CLASS(obj) \
- (G_TYPE_INSTANCE_GET_CLASS((obj), GALAGO_TYPE_SERVICE, GalagoServiceClass))
+ (G_TYPE_INSTANCE_GET_CLASS((obj), GALAGO_TYPE_SERVICE, \
+ GalagoServiceClass))
#define GALAGO_DBUS_SERVICE_INTERFACE "org.freedesktop.Galago.Service"
@@ -199,7 +221,7 @@
/**
* Adds an account to a service.
*
- * This is used internally. You don't need to call this.
+ * @internal This is used internally.
*
* @param service The service.
* @param account The account to add.
@@ -210,7 +232,7 @@
/**
* Removes an account from a service.
*
- * This is used internally. You don't need to call this.
+ * @internal This is used internally.
*
* @param service The service.
* @param account The account to remove.
Modified: trunk/libgalago/libgalago/galago-status.h
===================================================================
--- trunk/libgalago/libgalago/galago-status.h 2005-11-28 05:18:00 UTC (rev 2350)
+++ trunk/libgalago/libgalago/galago-status.h 2005-12-02 09:39:16 UTC (rev 2351)
@@ -1,5 +1,6 @@
/**
* @file libgalago/galago-status.h Galago Status API
+ * @ingroup Presence
*
* @Copyright (C) 2004-2005 Christian Hammond
*
@@ -39,11 +40,11 @@
typedef enum
{
- GALAGO_STATUS_ATTR_UNSET = -1,
- GALAGO_STATUS_ATTR_BOOL = 0,
- GALAGO_STATUS_ATTR_STRING,
- GALAGO_STATUS_ATTR_INT,
- GALAGO_STATUS_ATTR_DOUBLE
+ GALAGO_STATUS_ATTR_UNSET = -1, /**< Unset type */
+ GALAGO_STATUS_ATTR_BOOL = 0, /**< Boolean type */
+ GALAGO_STATUS_ATTR_STRING, /**< String type */
+ GALAGO_STATUS_ATTR_INT, /**< Integer type */
+ GALAGO_STATUS_ATTR_DOUBLE /**< Double type */
} GalagoStatusAttrType;
@@ -80,10 +81,12 @@
GalagoStatusPrivate *priv;
+#ifndef _DOXYGEN_
void (*reserved_1)(void);
void (*reserved_2)(void);
void (*reserved_3)(void);
void (*reserved_4)(void);
+#endif
};
/**
@@ -93,23 +96,38 @@
{
GalagoObjectClass parent_class;
+#ifndef _DOXYGEN_
void (*reserved_1)(void);
void (*reserved_2)(void);
void (*reserved_3)(void);
void (*reserved_4)(void);
+#endif
};
#define GALAGO_TYPE_STATUS (galago_status_get_type())
+
+/** Cast @c obj to a GalagoStatus. */
#define GALAGO_STATUS(obj) \
- (G_TYPE_CHECK_INSTANCE_CAST((obj), GALAGO_TYPE_STATUS, GalagoStatus))
+ (G_TYPE_CHECK_INSTANCE_CAST((obj), GALAGO_TYPE_STATUS, \
+ GalagoStatus))
+
+/** Cast @c klass to a GalagoStatus. */
#define GALAGO_STATUS_CLASS(klass) \
- (G_TYPE_CHECK_CLASS_CAST((klass), GALAGO_TYPE_STATUS, GalagoStatusClass))
+ (G_TYPE_CHECK_CLASS_CAST((klass), GALAGO_TYPE_STATUS, \
+ GalagoStatusClass))
+
+/** Check if @c obj is a GalagoStatus. */
#define GALAGO_IS_STATUS(obj) \
(G_TYPE_CHECK_INSTANCE_TYPE((obj), GALAGO_TYPE_STATUS))
+
+/** Check if @c klass is a GalagoStatusClass. */
#define GALAGO_IS_STATUS_CLASS(klass) \
(G_TYPE_CHECK_CLASS_TYPE((klass), GALAGO_TYPE_STATUS))
+
+/** Get the class for the GalagoStatus @c obj. */
#define GALAGO_STATUS_GET_CLASS(obj) \
- (G_TYPE_INSTANCE_GET_CLASS((obj), GALAGO_TYPE_STATUS, GalagoStatusClass))
+ (G_TYPE_INSTANCE_GET_CLASS((obj), GALAGO_TYPE_STATUS, \
+ GalagoStatusClass))
G_BEGIN_DECLS
@@ -157,7 +175,7 @@
/**
* Sets the parent presence of a status.
*
- * This should only be used internally.
+ * @internal This is used internally.
*
* @param status The status.
* @param presence The presence.
Modified: trunk/libgalago/libgalago/galago-value.h
===================================================================
--- trunk/libgalago/libgalago/galago-value.h 2005-11-28 05:18:00 UTC (rev 2350)
+++ trunk/libgalago/libgalago/galago-value.h 2005-12-02 09:39:16 UTC (rev 2351)
@@ -1,5 +1,6 @@
/**
* @file libgalago/galago-value.h Value wrapper API
+ * @ingroup Utility
*
* @Copyright (C) 2004-2005 Christian Hammond
*
@@ -50,6 +51,11 @@
G_BEGIN_DECLS
+/**************************************************************************/
+/** @name Value API */
+/**************************************************************************/
+/*@{*/
+
/**
* Creates a new GalagoValue.
*
@@ -377,6 +383,8 @@
const void **ret_array,
gsize *ret_size);
+/*@}*/
+
G_END_DECLS
#endif /* _GALAGO_VALUE_H_ */
Modified: trunk/libgalago/libgalago/galago.h
===================================================================
--- trunk/libgalago/libgalago/galago.h 2005-11-28 05:18:00 UTC (rev 2350)
+++ trunk/libgalago/libgalago/galago.h 2005-12-02 09:39:16 UTC (rev 2351)
@@ -34,4 +34,20 @@
#include <libgalago/galago-status.h>
#include <libgalago/galago-value.h>
+/**
+ * @mainpage libgalago
+ * @section intro_sec Introduction
+ *
+ * Galago is a desktop presence framework, designed to transmit presence
+ * information between programs. To put it in simpler terms, it takes
+ * information about who is online and their away/idle states from an instant
+ * messenger (such as gaim) or other similar programs and allows other
+ * programs (such as Novell Evolution) to make use of it.
+ *
+ * The project home page is at http://www.galago-project.org/.
+ *
+ * @defgroup Presence Presence functions
+ * @defgroup Utility Utility functions
+ */
+
#endif /* _GALAGO_H_ */
More information about the galago-commits
mailing list