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

7 files changed, 108 insertions, 57 deletions

diff --git a/ChangeLog b/ChangeLog
index df950c5b6a..cd35dee5af 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+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.
+
 1999-09-02  bertrand  <Bertrand.Guiheneuf@aful.org>
 
 	* camel/providers/maildir: Added (experimental) maildir 
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,
diff --git a/devel-docs/camel/Makefile.am b/devel-docs/camel/Makefile.am
index 176a06b879..276059cf88 100644
--- a/devel-docs/camel/Makefile.am
+++ b/devel-docs/camel/Makefile.am
@@ -24,6 +24,7 @@ tmpl_sources =					\
 	tmpl/camel-folder.sgml			\
 	tmpl/camel-mime-message.sgml		\
 	tmpl/camel-mime-part.sgml		\
+	tmpl/camel-recipient.sgml		\
 	tmpl/camel-service.sgml			\
 	tmpl/camel-store.sgml			\
 	tmpl/camel-stream.sgml		
diff --git a/devel-docs/camel/camel-docs.sgml b/devel-docs/camel/camel-docs.sgml
index ecbed2c093..33c6623731 100644
--- a/devel-docs/camel/camel-docs.sgml
+++ b/devel-docs/camel/camel-docs.sgml
@@ -3,6 +3,7 @@
 <!entity CamelFolder SYSTEM "sgml/camel-folder.sgml">
 <!entity CamelMimeMessage SYSTEM "sgml/camel-mime-message.sgml">
 <!entity CamelMimePart SYSTEM "sgml/camel-mime-part.sgml">
+<!entity CamelRecipient SYSTEM "sgml/camel-recipient.sgml">
 <!entity CamelService SYSTEM "sgml/camel-service.sgml">
 <!entity CamelStore SYSTEM "sgml/camel-store.sgml">
 <!entity CamelStream SYSTEM "sgml/camel-stream.sgml">
@@ -21,6 +22,7 @@
     &CamelFolder;
     &CamelMimePart;
     &CamelDataWrapper;
+    &CamelRecipient;
 
   </chapter>
 </book>
diff --git a/devel-docs/camel/camel-sections.txt b/devel-docs/camel/camel-sections.txt
index 4b0a36f9cc..1f6d45c03c 100644
--- a/devel-docs/camel/camel-sections.txt
+++ b/devel-docs/camel/camel-sections.txt
@@ -15,6 +15,19 @@ CAMEL_DATA_WRAPPER_CLASS
 </SECTION>
 
 <SECTION>
+<FILE>camel-recipient</FILE>
+CamelRecipientTable
+<TITLE>CamelRecipientTable</TITLE>
+camel_recipient_table_new
+camel_recipient_table_get
+camel_recipient_table_add
+camel_recipient_table_add_list
+camel_recipient_table_remove
+camel_recipient_table_ref
+camel_recipient_table_unref
+</SECTION>
+
+<SECTION>
 <FILE>camel-mime-part</FILE>
 CamelMimePart
 <TITLE>CamelMimePart</TITLE>
diff --git a/devel-docs/camel/tmpl/camel-mime-part.sgml b/devel-docs/camel/tmpl/camel-mime-part.sgml
index c680a24faf..2db158b25f 100644
--- a/devel-docs/camel/tmpl/camel-mime-part.sgml
+++ b/devel-docs/camel/tmpl/camel-mime-part.sgml
@@ -14,25 +14,6 @@ CamelMimePart
 
 </para>
 
-<!-- ##### FUNCTION camel_mime_part_add_header ##### -->
-<para>
-
-</para>
-
-@mime_part: 
-@header_name: 
-@header_value: 
-
-
-<!-- ##### FUNCTION camel_mime_part_set_content_object ##### -->
-<para>
-
-</para>
-
-@mime_part: 
-@content: 
-
-
 <!-- ##### FUNCTION camel_mime_part_set_filename ##### -->
 <para>
 
@@ -78,15 +59,6 @@ CamelMimePart
 @header_lines: 
 
 
-<!-- ##### FUNCTION camel_mime_part_get_content_object ##### -->
-<para>
-
-</para>
-
-@mime_part: 
-@Returns: 
-
-
 <!-- ##### FUNCTION camel_mime_part_get_content_id ##### -->
 <para>
 
@@ -132,15 +104,6 @@ CamelMimePart
 @disposition: 
 
 
-<!-- ##### FUNCTION camel_mime_part_remove_header ##### -->
-<para>
-
-</para>
-
-@mime_part: 
-@header_name: 
-
-
 <!-- ##### FUNCTION camel_mime_part_get_filename ##### -->
 <para>
 
@@ -186,13 +149,3 @@ CamelMimePart
 @Returns: 
 
 
-<!-- ##### FUNCTION camel_mime_part_get_header ##### -->
-<para>
-
-</para>
-
-@mime_part: 
-@header_name: 
-@Returns: 
-
-
diff --git a/devel-docs/camel/tmpl/camel-service.sgml b/devel-docs/camel/tmpl/camel-service.sgml
index fe132bfe67..5b51ea902e 100644
--- a/devel-docs/camel/tmpl/camel-service.sgml
+++ b/devel-docs/camel/tmpl/camel-service.sgml
@@ -19,6 +19,7 @@ CamelService
 
 </para>
 
+@e: 
 
 <!-- ##### FUNCTION camel_service_connect ##### -->
 <para>