ekiga r5919 - in trunk: . lib/engine/presence/avahi lib/engine/presence/local-roster lib/engine/presence/skel

[sfre svn gnome org]

Author: sfre
Date: Wed Jan 16 10:17:59 2008
New Revision: 5919
URL: http://svn.gnome.org/viewvc/ekiga?rev=5919&view=rev

Log:
Add a "presence" group in the engine reference documentation


Modified:
   trunk/ChangeLog
   trunk/lib/engine/presence/avahi/avahi-cluster.h
   trunk/lib/engine/presence/avahi/avahi-heap.h
   trunk/lib/engine/presence/avahi/avahi-main.h
   trunk/lib/engine/presence/avahi/avahi-presentity.h
   trunk/lib/engine/presence/local-roster/local-cluster.h
   trunk/lib/engine/presence/local-roster/local-heap.h
   trunk/lib/engine/presence/local-roster/local-presentity.h
   trunk/lib/engine/presence/local-roster/local-roster-bridge.h
   trunk/lib/engine/presence/local-roster/local-roster-main.h
   trunk/lib/engine/presence/skel/cluster-impl.h
   trunk/lib/engine/presence/skel/cluster.h
   trunk/lib/engine/presence/skel/heap-impl.h
   trunk/lib/engine/presence/skel/heap.h
   trunk/lib/engine/presence/skel/presence-core.h
   trunk/lib/engine/presence/skel/presentity.h

Modified: trunk/lib/engine/presence/avahi/avahi-cluster.h
==============================================================================
--- trunk/lib/engine/presence/avahi/avahi-cluster.h	(original)
+++ trunk/lib/engine/presence/avahi/avahi-cluster.h	Wed Jan 16 10:17:59 2008
@@ -44,6 +44,11 @@
 namespace Avahi
 {
 
+/**
+ * @addtogroup presence
+ * @{
+ */
+
   class Cluster:
     public Ekiga::ClusterImpl<Heap, Ekiga::delete_heap_management<Heap> >
   {
@@ -63,6 +68,10 @@
     Heap *heap;
   };
 
+/**
+ * @}
+ */
+
 };
 
 #endif

Modified: trunk/lib/engine/presence/avahi/avahi-heap.h
==============================================================================
--- trunk/lib/engine/presence/avahi/avahi-heap.h	(original)
+++ trunk/lib/engine/presence/avahi/avahi-heap.h	Wed Jan 16 10:17:59 2008
@@ -51,6 +51,11 @@
 namespace Avahi
 {
 
+/**
+ * @addtogroup presence
+ * @{
+ */
+
   class Heap: public Ekiga::HeapImpl<Presentity,Ekiga::delete_object_management<Presentity> >
   {
   public:
@@ -98,6 +103,10 @@
     AvahiServiceBrowser *browser;
   };
 
+/**
+ * @}
+ */
+
 };
 
 #endif

Modified: trunk/lib/engine/presence/avahi/avahi-main.h
==============================================================================
--- trunk/lib/engine/presence/avahi/avahi-main.h	(original)
+++ trunk/lib/engine/presence/avahi/avahi-main.h	Wed Jan 16 10:17:59 2008
@@ -40,8 +40,17 @@
 
 #include "services.h"
 
+/**
+ * @addtogroup presence
+ * @{
+ */
+
 bool avahi_init (Ekiga::ServiceCore &core,
 		 int *argc,
 		 char **argv[]);
 
+/**
+ * @}
+ */
+
 #endif

Modified: trunk/lib/engine/presence/avahi/avahi-presentity.h
==============================================================================
--- trunk/lib/engine/presence/avahi/avahi-presentity.h	(original)
+++ trunk/lib/engine/presence/avahi/avahi-presentity.h	Wed Jan 16 10:17:59 2008
@@ -46,6 +46,11 @@
 namespace Avahi
 {
 
+/**
+ * @addtogroup presence
+ * @{
+ */
+
   class Presentity: public Ekiga::Presentity
   {
   public:
@@ -84,6 +89,9 @@
     std::string url;
   };
 
+/**
+ * @}
+ */
 };
 
 #endif

Modified: trunk/lib/engine/presence/local-roster/local-cluster.h
==============================================================================
--- trunk/lib/engine/presence/local-roster/local-cluster.h	(original)
+++ trunk/lib/engine/presence/local-roster/local-cluster.h	Wed Jan 16 10:17:59 2008
@@ -42,6 +42,11 @@
 
 namespace Local
 {
+/**
+ * @addtogroup presence
+ * @{
+ */
+
   class Cluster :
     public Ekiga::ClusterImpl<Heap, Ekiga::delete_heap_management<Heap> >,
     public Ekiga::Trigger
@@ -78,6 +83,10 @@
     void on_status_received (std::string uri,
 			     std::string status);
   };
+
+/**
+ * @}
+ */
 }
 
 #endif

Modified: trunk/lib/engine/presence/local-roster/local-heap.h
==============================================================================
--- trunk/lib/engine/presence/local-roster/local-heap.h	(original)
+++ trunk/lib/engine/presence/local-roster/local-heap.h	Wed Jan 16 10:17:59 2008
@@ -58,6 +58,11 @@
 
 namespace Local
 {
+/**
+ * @addtogroup presence
+ * @{
+ */
+
   class Heap : public Ekiga::HeapImpl<Presentity, Ekiga::delete_object_management <Presentity> >
   {
   public:
@@ -167,6 +172,11 @@
     Ekiga::PresenceCore *presence_core;
     xmlDocPtr doc;
   };
+
+/**
+ * @}
+ */
+
 };
 
 #endif

Modified: trunk/lib/engine/presence/local-roster/local-presentity.h
==============================================================================
--- trunk/lib/engine/presence/local-roster/local-presentity.h	(original)
+++ trunk/lib/engine/presence/local-roster/local-presentity.h	Wed Jan 16 10:17:59 2008
@@ -54,6 +54,11 @@
 
 namespace Local
 {
+/**
+ * @addtogroup presence
+ * @{
+ */
+
   class Presentity: public Ekiga::Presentity
   {
   public:
@@ -171,6 +176,10 @@
     std::map<std::string, xmlNodePtr> group_nodes;
     std::set<std::string> groups;
   };
+
+/**
+ * @}
+ */
 };
 
 #endif

Modified: trunk/lib/engine/presence/local-roster/local-roster-bridge.h
==============================================================================
--- trunk/lib/engine/presence/local-roster/local-roster-bridge.h	(original)
+++ trunk/lib/engine/presence/local-roster/local-roster-bridge.h	Wed Jan 16 10:17:59 2008
@@ -40,8 +40,16 @@
 
 #include "services.h"
 
+/**
+ * @addtogroup presence
+ * @{
+ */
+
 bool local_roster_bridge_init (Ekiga::ServiceCore &core,
 			       int *argc,
 			       char **argv[]);
 
+/**
+ * @}
+ */
 #endif

Modified: trunk/lib/engine/presence/local-roster/local-roster-main.h
==============================================================================
--- trunk/lib/engine/presence/local-roster/local-roster-main.h	(original)
+++ trunk/lib/engine/presence/local-roster/local-roster-main.h	Wed Jan 16 10:17:59 2008
@@ -40,8 +40,17 @@
 
 #include "services.h"
 
+/**
+ * @addtogroup presence
+ * @{
+ */
+
 bool local_roster_init (Ekiga::ServiceCore &core,
 			int *argc,
 			char **argv[]);
 
+/**
+ * @}
+ */
+
 #endif

Modified: trunk/lib/engine/presence/skel/cluster-impl.h
==============================================================================
--- trunk/lib/engine/presence/skel/cluster-impl.h	(original)
+++ trunk/lib/engine/presence/skel/cluster-impl.h	Wed Jan 16 10:17:59 2008
@@ -42,28 +42,13 @@
 #include "map-key-const-reference-iterator.h"
 #include "cluster.h"
 
-/* This class is there to make it easy to implement a new type of
- * cluster : it will take care of implementing the external api, you
- * just have to decide when to add and remove heaps.
- *
- * It also provides basic memory management for heaps, with the second
- * (optional) template argument :
- * - either no management (the default) ;
- * - or the heap is considered bound to one cluster, which will trigger its
- * destruction (using delete) when removed from it, which can happen in two
- * ways : either by calling the remove_heap method, or by emission of the
- * heap's removed signal.
- *
- * Notice that this class won't take care of removing the heap from a
- * backend -- only from the cluster. If you want the heap *deleted* then you
- * probably should have an organization like :
- * - the heap has a 'deleted' signal ;
- * - the cluster listens for this signal ;
- * - when the signal is received, then do a remove_heap followed by calling
- * the appropriate api function to delete the heap in your backend.
- */
+namespace Ekiga
+{
 
-namespace Ekiga {
+/**
+ * @addtogroup presence
+ * @{
+ */
 
   template<typename HeapType>
   struct no_heap_management
@@ -82,6 +67,30 @@
 
   };
 
+  /** Generic implementation for the Cluster pure virtual class.
+   *
+   * This class is there to make it easy to implement a new type of
+   * cluster: it will take care of implementing the external api, you
+   * just have to decide when to add and remove heaps.
+   *
+   * It also provides basic memory management for heaps, with the second
+   * (optional) template argument:
+   *  - either no management (the default);
+   *  - or the heap is considered bound to one cluster, which will trigger its
+   *    destruction (using delete) when removed from it, which can happen in
+   *    two ways: either by calling the remove_heap method, or by emission of
+   *    the Heap's removed signal.
+   *
+   * Notice that this class won't take care of removing the heap from a
+   * backend -- only from the cluster. If you want the heap <b>deleted</b> then
+   * you probably should have an organization like:
+   *  - the heap has a 'deleted' signal;
+   *  - the cluster listens for this signal;
+   *  - when the signal is received, then do a remove_heap followed by calling
+   *    the appropriate api function to delete the Heap in your backend.
+   */
+
+
   template<typename HeapType = Heap,
 	   typename HeapManagementTrait = no_heap_management <HeapType> >
   class ClusterImpl: public Cluster
@@ -127,6 +136,10 @@
     std::map<HeapType *, std::vector<sigc::connection> > connections;
   };
 
+/**
+ * @}
+ */
+
 };
 
 /* here are the implementations of the template methods */

Modified: trunk/lib/engine/presence/skel/cluster.h
==============================================================================
--- trunk/lib/engine/presence/skel/cluster.h	(original)
+++ trunk/lib/engine/presence/skel/cluster.h	Wed Jan 16 10:17:59 2008
@@ -39,7 +39,13 @@
 
 #include "heap.h"
 
-namespace Ekiga {
+namespace Ekiga
+{
+
+/**
+ * @addtogroup presence
+ * @{
+ */
 
   class Cluster
   {
@@ -80,6 +86,10 @@
     ChainOfResponsibility<FormRequest*> questions;
   };
 
+/**
+ * @}
+ */
+
 };
 
 #endif

Modified: trunk/lib/engine/presence/skel/heap-impl.h
==============================================================================
--- trunk/lib/engine/presence/skel/heap-impl.h	(original)
+++ trunk/lib/engine/presence/skel/heap-impl.h	Wed Jan 16 10:17:59 2008
@@ -40,30 +40,37 @@
 #include "lister.h"
 #include "heap.h"
 
-/* This class is there to make it easy to implement a new type of presentity
- * heap : it will take care of implementing the external api, you
- * just have to decide when to add and remove presentities.
- *
- * It also provides basic memory management for presentities, with the second
- * (optional) template argument :
- * - either no management (the default) ;
- * - or the presentity is considered bound to one heap, which will trigger its
- * destruction (using delete) when removed from it, which can happen in two
- * ways : either by calling the remove_presentity method, or by emission of the
- * presentity's removed signal.
- *
- * Notice that this class won't take care of removing the presentity from a
- * backend -- only from the heap. If you want the presentity *deleted* then you
- * probably should have an organization like :
- * - the presentity has a 'deleted' signal ;
- * - the heap listens for this signal ;
- * - when the signal is received, then do a remove_presentity followed by
- * calling the appropriate api function to delete the presentity in your
- * backend.
- */
+namespace Ekiga
+{
 
-namespace Ekiga {
+/**
+ * @addtogroup presence
+ * @{
+ */
 
+  /** Generic implementation for the Heap pure virtual class.
+   *
+   * This class is there to make it easy to implement a new type of presentity
+   * heap: it will take care of implementing the external api, you
+   * just have to decide when to add and remove presentities.
+   *
+   * It also provides basic memory management for presentities, with the second
+   * (optional) template argument:
+   *  - either no management (the default);
+   *  - or the presentity is considered bound to one heap, which will trigger
+   *    its destruction (using delete) when removed from it, which can happen
+   *    in two ways: either by calling the remove_presentity method, or by
+   *    emission of the presentity's removed signal.
+   *
+   * Notice that this class won't take care of removing the presentity from a
+   * backend -- only from the heap. If you want the presentity <b>deleted</b>
+   * then you probably should have an organization like:
+   *  - the presentity has a 'deleted' signal;
+   *  - the heap listens for this signal;
+   *  - when the signal is received, then do a remove_presentity followed by
+   *    calling the appropriate api function to delete the presentity in your
+   *    backend.
+   */
   template<typename PresentityType = Presentity,
 	   typename ObjectManagementTrait = no_object_management<PresentityType> >
   class HeapImpl:
@@ -97,6 +104,10 @@
     void remove_presentity (PresentityType &presentity);
   };
 
+/**
+ * @}
+ */
+
 };
 
 /* here are the implementations of the template methods */

Modified: trunk/lib/engine/presence/skel/heap.h
==============================================================================
--- trunk/lib/engine/presence/skel/heap.h	(original)
+++ trunk/lib/engine/presence/skel/heap.h	Wed Jan 16 10:17:59 2008
@@ -40,7 +40,13 @@
 
 #include "presentity.h"
 
-namespace Ekiga {
+namespace Ekiga
+{
+
+/**
+ * @addtogroup presence
+ * @{
+ */
 
   class Heap
   {
@@ -95,6 +101,9 @@
     ChainOfResponsibility<FormRequest*> questions;
   };
 
+/**
+ * @}
+ */
 };
 
 #endif

Modified: trunk/lib/engine/presence/skel/presence-core.h
==============================================================================
--- trunk/lib/engine/presence/skel/presence-core.h	(original)
+++ trunk/lib/engine/presence/skel/presence-core.h	Wed Jan 16 10:17:59 2008
@@ -41,27 +41,15 @@
 #include "services.h"
 #include "cluster.h"
 
-/* The presence core has several goals :
- * - one of them is of course to list presentities, and know what happens to
- * them ;
- * - another one is that we may want to store presentities somewhere as dead
- * data, but still be able to gain presence information and actions on them.
- *
- * This is obtained by using three types of helpers :
- * - the abstract class PresentityDecorator, which allows to enable actions on
- * presentities based on uris ;
- * - the abstract class PresenceFetcher, through which it is possible to gain
- * presence information : they allow the PresenceCore to declare some presence
- * information is needed about an uri, or now unneeded ;
- * - finally, a simple callback-based api allows to add detecters for supported
- * uris : this allows for example a Presentity to know if it should declare
- * an uri as "foo bar" or as "prtcl:foo bar". FIXME : couldn't a chain of
- * responsibility be used there instead of a special registering magic?
+namespace Ekiga
+{
+
+/**
+ * @defgroup presence Presence
+ * @{
  */
 
 
-namespace Ekiga
-{
   class PresentityDecorator
   {
   public:
@@ -118,11 +106,31 @@
     virtual void publish (const std::string & /*presence*/,
                           const std::string & /*extended_status*/) = 0;
   };
-};
-
-namespace Ekiga
-{
 
+  /** Core object for the presence support.
+   *
+   * The presence core has several goals:
+   *  - one of them is of course to list presentities, and know what happens to
+   *    them;
+   *  - another one is that we may want to store presentities somewhere as dead
+   *    data, but still be able to gain presence information and actions on
+   *    them.
+   *
+   * This is achieved by using three types of helpers:
+   *  - the abstract class PresentityDecorator, which allows to enable actions
+   *    on presentities based on uris;
+   * - the abstract class PresenceFetcher, through which it is possible to gain
+   *   presence information: they allow the PresenceCore to declare some
+   *   presence information is needed about an uri, or now unneeded;
+   * - finally, a simple callback-based api allows to add detecters for
+   *   supported uris: this allows for example a Presentity to know if it
+   *   should declare an uri as "foo bar" or as "prtcl:foo bar".
+   */
+
+  /*
+   * FIXME : couldn't a chain of responsibility be used there instead of a
+   *         special registering magic?
+   */
   class PresenceCore:
     public Service
   {
@@ -293,6 +301,10 @@
 
   };
 
+/**
+ * @}
+ */
+
 };
 
 #endif

Modified: trunk/lib/engine/presence/skel/presentity.h
==============================================================================
--- trunk/lib/engine/presence/skel/presentity.h	(original)
+++ trunk/lib/engine/presence/skel/presentity.h	Wed Jan 16 10:17:59 2008
@@ -46,6 +46,13 @@
 namespace Ekiga
 {
 
+/**
+ * @addtogroup presence
+ * @{
+ */
+
+  /** A presentity is a piece of presence information for a single URI.
+   */
   class Presentity
   {
   public:
@@ -102,6 +109,9 @@
     ChainOfResponsibility<FormRequest*> questions;
   };
 
+/**
+ * @}
+ */
 };
 
 #endif