soylent r295 - in trunk: docs/reference/libsoylent libsoylent

[svenp svn gnome org]

Author: svenp
Date: Mon Aug 18 15:39:45 2008
New Revision: 295
URL: http://svn.gnome.org/viewvc/soylent?rev=295&view=rev

Log:
updated documentation
added section-description for every section

Modified:
   trunk/docs/reference/libsoylent/libsoylent-docs.sgml
   trunk/docs/reference/libsoylent/libsoylent-sections.txt
   trunk/libsoylent/sl-attribute-eds.c
   trunk/libsoylent/sl-attributes.c
   trunk/libsoylent/sl-book.c
   trunk/libsoylent/sl-entity-eds.c
   trunk/libsoylent/sl-person.c
   trunk/libsoylent/soylent.c

Modified: trunk/docs/reference/libsoylent/libsoylent-docs.sgml
==============================================================================
--- trunk/docs/reference/libsoylent/libsoylent-docs.sgml	(original)
+++ trunk/docs/reference/libsoylent/libsoylent-docs.sgml	Mon Aug 18 15:39:45 2008
@@ -21,10 +21,13 @@
     <title>libsoylent API Reference</title>
     <xi:include href="xml/soylent.xml"/>
     <xi:include href="xml/sl-book.xml"/>
-    <xi:include href="xml/sl-entity.xml"/>
+    <xi:include href="xml/sl-person.xml"/>
     <xi:include href="xml/sl-attribute.xml"/>
+    <xi:include href="xml/sl-attributes.xml"/>
     <xi:include href="xml/well-known-attributes.xml" />
-    <xi:include href="xml/sl-person.xml"/>
+    <xi:include href="xml/sl-attribute-types.xml"/>
+    <xi:include href="xml/sl-entity.xml"/>
+
     <!--<xi:include href="xml/sl-group.xml"/>
         <xi:include href="xml/sl-entity-handler.xml"/>
         <xi:include href="xml/sl-entity-handler-file.xml"/>

Modified: trunk/docs/reference/libsoylent/libsoylent-sections.txt
==============================================================================
--- trunk/docs/reference/libsoylent/libsoylent-sections.txt	(original)
+++ trunk/docs/reference/libsoylent/libsoylent-sections.txt	Mon Aug 18 15:39:45 2008
@@ -1,5 +1,8 @@
 <SECTION>
 <FILE>sl-person</FILE>
+<TITLE>SlPerson</TITLE>
+SL_PERSON_COMMUNICATION_CHAT_CB
+SlPersonCommunicateChatCb
 SL_PERSON_TYPE
 SlPerson
 SlPersonClass
@@ -31,6 +34,19 @@
 sl_person_set_full_name
 sl_person_set_name
 sl_person_set_nick
+sl_person_communicate_call
+sl_person_communicate_chat
+sl_person_communicate_chat_async
+sl_person_communicate_chat_from
+sl_person_communicate_chat_from_async
+sl_person_communicate_chat_to
+sl_person_communicate_chat_to_async
+sl_person_communicate_email
+sl_person_get_imcontacts
+sl_person_get_presence
+sl_person_get_string
+sl_person_has_iminfo
+sl_person_is_online
 <SUBSECTION Standard>
 SL_PERSON
 SL_IS_PERSON
@@ -42,6 +58,7 @@
 SlPersonPriv
 sl_person_new_with_econtact
 sl_person_constr_with_econtact
+sl_person_launch_chat
 </SECTION>
 
 <SECTION>
@@ -67,10 +84,6 @@
 SlEntity
 SlEntityClass
 sl_entity_constr
-sl_entity_constr_with_econtact
-sl_entity_set_ebook
-sl_entity_get_ebook
-sl_entity_get_econtact
 sl_entity_commit
 sl_entity_add_attribute
 sl_entity_remove_attribute
@@ -89,12 +102,24 @@
 sl_entity_has_attribute
 sl_entity_modified
 sl_entity_modified_at
+sl_entity_get_imcontacts
+sl_entity_get_presence
+sl_entity_has_iminfo
+sl_entity_is_online
 <SUBSECTION Private>
+sl_entity_constr_with_econtact
+sl_entity_get_econtact
 sl_entity_add_attribute_shallow
 sl_entity_get_attribute_create
 sl_entity_get_attribute_from_eattr
 sl_entity_remove_attribute_shallow
 sl_entity_set_econtact
+sl_entity_set_storage
+sl_entity_associate_imcontact
+sl_entity_associate_imcontacts
+sl_entity_deassociate_imcontact
+sl_entity_get_imcontact_from_account_id
+sl_entity_get_imcontact_from_id
 sl_is_ignored_eattr
 <SUBSECTION Standard>
 SL_ENTITY
@@ -122,6 +147,7 @@
 SlBookCBPersonAttributeRemoved
 SlBookCBPersonModified
 SlBookCBPersonRemoved
+SlBookPersonPresenceChangedCb
 sl_book_constr
 sl_book_get_books
 sl_book_exists
@@ -133,6 +159,8 @@
 sl_book_remove_person
 sl_book_get_people
 sl_book_get_person
+sl_book_get_online_people
+sl_book_commit_person
 <SUBSECTION Standard>
 SL_BOOK
 SL_IS_BOOK
@@ -149,12 +177,16 @@
 sl_book_emit_person_attribute_modified
 sl_book_emit_person_attribute_removed
 sl_book_emit_person_removed
+sl_book_emit_person_presence_changed
 </SECTION>
 
 <SECTION>
 <FILE>soylent</FILE>
+<TITLE>soylent</TITLE>
 sl_init
 sl_cleanup
+sl_im_get_contact_manager
+sl_im_is_im_attribute
 sl_marshal_VOID__OBJECT_BOOLEAN
 sl_marshal_VOID__OBJECT_OBJECT_BOOLEAN
 sl_marshal_VOID__OBJECT_OBJECT_POINTER_BOOLEAN
@@ -282,4 +314,11 @@
 SL_ATTR_PHOTO
 SL_ATTR_TELEPHONE
 SL_ATTR_URL
+SL_ATTR_AIM
+SL_ATTR_GADUGADU
+SL_ATTR_GROUPWISE
+SL_ATTR_ICQ
+SL_ATTR_JABBER
+SL_ATTR_MSN
+SL_ATTR_YAHOO
 </SECTION>

Modified: trunk/libsoylent/sl-attribute-eds.c
==============================================================================
--- trunk/libsoylent/sl-attribute-eds.c	(original)
+++ trunk/libsoylent/sl-attribute-eds.c	Mon Aug 18 15:39:45 2008
@@ -21,6 +21,16 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  */
 
+/**
+ * SECTION:sl-attribute
+ * @short_description: an attribute of a #SlEntity
+ * @stability: Unstable
+ * @include: sl-attribute.h
+ *
+ * #SlAttribute is an attribute that holds a list of values. Arbitrary values
+ * can be added, removed and modified.
+ */
+
 #include "sl-mutual-inclusion.h"
 #include "sl-priv-util.h"
 #include "sl-attributes.h"
@@ -197,8 +207,6 @@
   const gchar *name = g_hash_table_lookup (eattrname_to_name_map, eattrname);
   if (name == NULL)
     {
-      
-      /* TODO: this leaks, cause name must be freed somehow */
       if (!g_str_has_prefix (eattrname, "X-"))
         {
           /* workaround for illegal vCard fields */
@@ -210,6 +218,7 @@
         }
       else
         {
+          /* FIXME: this leaks, cause name must be freed somehow */
           name = g_utf8_strdown (&eattrname[2], -1);
         }
     }

Modified: trunk/libsoylent/sl-attributes.c
==============================================================================
--- trunk/libsoylent/sl-attributes.c	(original)
+++ trunk/libsoylent/sl-attributes.c	Mon Aug 18 15:39:45 2008
@@ -21,6 +21,16 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  */
 
+/**
+ * SECTION:sl-attributes
+ * @short_description: a system where attributes can be registered and mapped to
+ * runtime-types
+ * @stability: Unstable
+ * @include: sl-attributes.h
+ *
+ * TODO: add description and an example in libsoylent/example
+ */
+
 #include "sl-attributes.h"
 #include "sl-priv-util.h"
 
@@ -191,7 +201,7 @@
     }
   if (to_string == NULL)
     {
-      return "-";
+      return NULL;
     }
   else
     {

Modified: trunk/libsoylent/sl-book.c
==============================================================================
--- trunk/libsoylent/sl-book.c	(original)
+++ trunk/libsoylent/sl-book.c	Mon Aug 18 15:39:45 2008
@@ -24,11 +24,10 @@
 /**
  * SECTION:sl-book
  * @short_description: the addressbook
- * @see_also: #SlEntity
  * @stability: Unstable
  * @include: sl-book.h
  *
- * SlBook is basically like a real-world addressbook, i.e. it is responsible
+ * #SlBook is basically like a real-world addressbook, i.e. it is responsible
  * for managing people (adding and removing them to / from the addressbook).
  * Searching for people is also possible. Furthermore SlBook contains utility
  * functions to create, open and delete addressbooks.
@@ -582,22 +581,6 @@
   return NULL;
 }
 
-/*static SlPerson *
-sl_book_get_person_from_econtact (SlBook *self, EContact *econtact)
-{
-  GList *people = self->priv->people;
-  for (; people != NULL; people = people->next)
-    {
-      SlPerson *person = people->data;
-      if (sl_entity_get_econtact (SL_ENTITY (person)) == econtact)
-        {
-          return person;
-        }
-    }
-  
-  return NULL;
-}*/
-
 void
 sl_book_emit_person_presence_changed (SlBook *self, SlPerson *person)
 {
@@ -783,67 +766,7 @@
       g_list_free (g_list_first (modified));
       sl_priv_util_eattribute_deep_list_free (eattributes);
       sl_priv_util_eattribute_deep_list_free (eattributes_old);
-      
-      /*
-      sl_priv_util_eattribute_list_print (eattributes, "eattributes");
-      
-      sl_debug_book ("examining %d eattribute(s)", g_list_length (eattributes));
-      for (; eattributes != NULL; eattributes = eattributes->next)
-        {
-          
-          
-          EVCardAttribute *eattr = eattributes->data;
-          const gchar *eattrname = e_vcard_attribute_get_name (eattr);
-          if (sl_is_ignored_eattr (eattrname))
-            {
-              sl_debug_book ("ignoring eattribute \"%s\"", eattrname);
-              continue;
-            }
-
-          EVCardAttribute *eattr_old = e_vcard_get_attribute (E_VCARD (econtact_old), eattrname);
-          
-          if (eattr_old == NULL)
-            {
-              sl_debug_book ("found new eattribute \"%s\"", eattrname);
-              SlAttribute *attr = sl_attribute_new_with_eattr (eattr);
-              sl_person_add_attribute (person, attr);
-              sl_book_emit_person_attribute_added (self, person, attr, FALSE);
-              g_object_unref (attr);
-            }
-          else
-            {
-              GList *evalues = e_vcard_attribute_get_values (eattr);
-              GList *evalues_old = e_vcard_attribute_get_values (eattr_old);
-              if (!sl_priv_util_lists_equal (evalues, evalues_old, g_str_equal))
-                {
-                  sl_debug_book ("found modified eattribute \"%s\"", eattrname);
-                  SlAttribute *attr = sl_entity_get_attribute_from_eattr (entity, eattr_old);
-                  g_assert (attr != NULL);
-                  GList *old_values = sl_attribute_get_all (attr);
-                  sl_attribute_set_all_from_eattr (attr, eattr);
-                  sl_book_emit_person_attribute_modified (self, person, attr, old_values, FALSE);
-                }
-              eattributes_old = g_list_remove (eattributes_old, eattr_old);
-            }
-        }
-      
-      for (; eattributes_old != NULL; eattributes_old = eattributes_old->next)
-        {
-          EVCardAttribute *eattr_old = eattributes_old->data;
-          const gchar *eattrname_old = e_vcard_attribute_get_name (eattr_old);
-          if (sl_is_ignored_eattr (eattrname_old))
-            {
-              sl_debug_book ("ignoring eattribute \"%s\"", eattrname_old);
-              continue;
-            }
-          sl_debug_book ("eattribute \"%s\" doesn't exist anymore", e_vcard_attribute_get_name (eattr_old));
-          SlAttribute *attr = sl_entity_get_attribute_from_eattr (entity, eattr_old);
-          g_assert (attr != NULL);
-          sl_book_emit_person_attribute_removed (self, person, attr, FALSE);
-        }
-      */
-      
-      
+     
       //g_object_unref (econtact_old);
     }
 }

Modified: trunk/libsoylent/sl-entity-eds.c
==============================================================================
--- trunk/libsoylent/sl-entity-eds.c	(original)
+++ trunk/libsoylent/sl-entity-eds.c	Mon Aug 18 15:39:45 2008
@@ -24,6 +24,16 @@
 /* TODO: will be splitted to SlEntity (interface), SlEntityBase (abstract-
  * base class), SlEntityEDS. for now this will be misused as SlEntityEDS */
 
+/**
+ * SECTION:sl-entity
+ * @short_description: a entity (holding attributes)
+ * @stability: Unstable
+ * @include: sl-entity.h
+ *
+ * #SlEntity is a storage for attributes (#SlAttribute). Attributes can be
+ * added, removed and modified.
+ */
+
 #include "sl-mutual-inclusion.h"
 #include "sl-priv-util.h"
 #include "soylent.h"

Modified: trunk/libsoylent/sl-person.c
==============================================================================
--- trunk/libsoylent/sl-person.c	(original)
+++ trunk/libsoylent/sl-person.c	Mon Aug 18 15:39:45 2008
@@ -21,6 +21,35 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  */
 
+/**
+ * SECTION:sl-person
+ * @short_description: a person
+ * @stability: Unstable
+ * @include: sl-person.h
+ *
+ * #SlPerson represents a real-world person. A person has attributes
+ * (#SlAttribute) that can be added, removed and modified.
+ */
+
+/**
+ * SECTION:well-known-attributes
+ * @short_description: descriptions of all well-known attributes
+ * @stability: Unstable
+ * @include: sl-person.h
+ *
+ * A well-known attribute is an attribute that's name is known to the system
+ * (e.g. nick, email). Every attribute has a description and a runtime-type.
+ */
+
+/**
+ * SECTION:sl-attribute-types
+ * @short_description: runtime-types of attribute-values
+ * @stability: Unstable
+ * @include: sl-person.h
+ *
+ * Some structs to make your life with attributes easier.
+ */
+
 #include "sl-mutual-inclusion.h"
 
 #include <libempathy/empathy-utils.h>

Modified: trunk/libsoylent/soylent.c
==============================================================================
--- trunk/libsoylent/soylent.c	(original)
+++ trunk/libsoylent/soylent.c	Mon Aug 18 15:39:45 2008
@@ -21,6 +21,16 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  */
 
+/**
+ * SECTION:soylent
+ * @short_description: global libsoylent functions
+ * @stability: Unstable
+ * @include: soylent.h
+ *
+ * soylent contains some global functions for libsoylent, like initializing
+ * and cleaning up libsoylent.
+ */
+
 #include "soylent.h"
 #include "sl-priv-util.h"