sgml doc has camel-recipient now.

1999-09-03  bertrand  <Bertrand.Guiheneuf@aful.org>

	* devel-docs/camel/Makefile.am:
	sgml doc has camel-recipient now.

	* camel/camel-recipient.c (camel_recipient_foreach_recipient_type):
	added in-line documentation.

svn path=/trunk/; revision=1174

1 files changed, 83 insertions, 10 deletions

diff --git a/camel/camel-recipient.c b/camel/camel-recipient.c
index 436af5058b..f1b18bea24 100644
--- a/camel/camel-recipient.c
+++ b/camel/camel-recipient.c
@@ -27,6 +27,17 @@
 #include "camel-recipient.h"
 
 
+/**
+ * camel_recipient_table_new: Create a new recipient table object
+ * 
+ * 
+ * creates a new recipient table object. A recipient table 
+ * objects merely associates a recipient list (GList) to
+ * recipient types (as for example "To", "Cc" for mime
+ * maile messages 
+ *
+ * Return value: the newly created recipient table object
+ **/
 CamelRecipientTable *
 camel_recipient_table_new ()
 {
@@ -39,6 +50,12 @@ camel_recipient_table_new ()
 }
 
 
+/**
+ * camel_recipient_table_ref: add a reference to a recipient table object
+ * @recipient_table: the recipient table object
+ * 
+ * Add a reference to a recipient table object. 
+ **/
 void 
 camel_recipient_table_ref (CamelRecipientTable *recipient_table)
 {
@@ -63,6 +80,13 @@ _free_recipient_list (gpointer key, gpointer value, gpointer user_data)
 	
 }
 
+/**
+ * camel_recipient_table_free: Free a recipient table object
+ * @recipient_table: the recipient table object to free
+ * 
+ * Free a recipient table object. All recipients and recipient
+ * are freed. 
+ **/
 void 
 camel_recipient_table_free (CamelRecipientTable *recipient_table)
 {
@@ -76,6 +100,15 @@ camel_recipient_table_free (CamelRecipientTable *recipient_table)
 
 
 
+/**
+ * camel_recipient_table_unref: Removes a reference to a recipient table object
+ * @recipient_table: the recipient table object
+ * 
+ * Removes a reference to the reference count of a recipient
+ * table object. If the reference count falls to zero, the 
+ * recipient table object is freed.
+ *
+ **/
 void 
 camel_recipient_table_unref (CamelRecipientTable *recipient_table)
 {
@@ -89,13 +122,18 @@ camel_recipient_table_unref (CamelRecipientTable *recipient_table)
 
 
 
+
 /**
- * camel_recipient_table_add:
- * @recipient_table: 
- * @recipient_type: 
- * @recipient: 
- * 
+ * camel_recipient_table_add: Add a recipient to a recipient table object.
+ * @recipient_table: The recipient table object
+ * @recipient_type: Recipient type string
+ * @recipient:  The recipient to add
  * 
+ * Add a recipient to a recipient table object. 
+ * The recipient is appended to the list of recipients
+ * of type @recipient_type. @recipient and @recipient_type
+ * are duplicated if necessary and freed when 
+ * camel_recipient_table_free is called.
  **/
 void 
 camel_recipient_table_add (CamelRecipientTable *recipient_table, 
@@ -122,12 +160,15 @@ camel_recipient_table_add (CamelRecipientTable *recipient_table,
 
 
 /**
- * camel_recipient_table_add_list:
- * @recipient_table: 
- * @recipient_type: 
- * @recipient_list: 
+ * camel_recipient_table_add_list: Add a full list of recipients to a recipient table.
+ * @recipient_table: The recipient table object
+ * @recipient_type:  Recipient type string.
+ * @recipient_list: Recipient list to add.
  * 
- * be careful, that the list is used as is, and its element
+ * Add a full list of recipients to a recipient table.
+ * The new recipients are appended at the end of the
+ * existing recipient list corresponding to @recipient_type.
+ * Be careful, the list is used as is, and its element
  * will be freed by camel_recipient_table_unref
  **/
 void 
@@ -151,6 +192,17 @@ camel_recipient_table_add_list (CamelRecipientTable *recipient_table,
 
 
 
+/**
+ * camel_recipient_table_remove: Remove a recipient from a recipient table.
+ * @recipient_table: The recipient table object
+ * @recipient_type: Recipient type string.
+ * @recipient: Recipient to remove from the table
+ * 
+ * Remove a recipient from a recipient table. The recipient is
+ * only removed from the recipient list corresponding to 
+ * @recipient_type. The removed recipient is freed.
+ *
+ **/
 void
 camel_recipient_table_remove (CamelRecipientTable *recipient_table,
 			      const gchar *recipient_type,
@@ -186,6 +238,19 @@ camel_recipient_table_remove (CamelRecipientTable *recipient_table,
 
 
 
+/**
+ * camel_recipient_table_get: Get the recipients corresponding to a recipient type.
+ * @recipient_table: The recipient table object
+ * @recipient_type: Recipient type string.
+ * 
+ * Return the list of recipients corresponding to 
+ * @recipient_type. The returned list is not a copy 
+ * of the internal list used by the recipient table object
+ * but the list itself. It thus must not be freed.
+ * The recipients it contains can be modified.
+ * 
+ * Return value: The list of recipients.
+ **/
 const GList *
 camel_recipient_table_get (CamelRecipientTable *recipient_table,
 			   const gchar *recipient_type)
@@ -196,6 +261,14 @@ camel_recipient_table_get (CamelRecipientTable *recipient_table,
 
 
 
+/**
+ * camel_recipient_foreach_recipient_type: Runs a function over over all recipients type lists.
+ * @recipient_table: The recipient table object.
+ * @func: The function to run.
+ * @user_data: User data to pass to the function.
+ * 
+ * Runs a function over over all recipients type lists.
+ **/
 void
 camel_recipient_foreach_recipient_type (CamelRecipientTable *recipient_table,
 					CRLFunc func,