updated some autogen doc stuff. Still don't understand warnings :(

1999-08-06  bertrand  <Bertrand.Guiheneuf@aful.org>

	* devel-docs/camel/:
	updated some autogen doc stuff.
	Still don't understand warnings :(

	* camel/camel-data-wrapper.c:
	* camel/providers/MH/camel-mh-store.c:
	* camel/url-util.c:
	* camel/gmime-content-field.c:
	* camel/camel-store.c:
	various inline doc corrections.

	* camel/camel-folder.c (get_message_count):
	new method. Returns the number of message
	in the folder.

svn path=/trunk/; revision=1092

8 files changed, 87 insertions, 61 deletions

diff --git a/camel/camel-data-wrapper.c b/camel/camel-data-wrapper.c
index b6a9f9ea3e..ef8c325293 100644
--- a/camel/camel-data-wrapper.c
+++ b/camel/camel-data-wrapper.c
@@ -100,7 +100,7 @@ camel_data_wrapper_get_type (void)
 /**
  * _write_to_stream: write data content in a byte stream
  * @data_wrapper: the data wrapper object
- * @stre:m byte stream where data will be written 
+ * @stream byte stream where data will be written 
  * 
  * This method must be overriden by subclasses
  * Data must be written in the bytes stream
@@ -121,7 +121,7 @@ _write_to_stream (CamelDataWrapper *data_wrapper, CamelStream *stream)
 
 /**
  * camel_data_wrapper_write_to_stream: write data in a stream
- * @data_wrappewr: the data wrapper object
+ * @data_wrapper: the data wrapper object
  * @stream: byte stream where data will be written 
  *
  * Write data content in a stream. Data is stored in a machine
diff --git a/camel/camel-folder.c b/camel/camel-folder.c
index bdd1a75a17..5fa22a5b72 100644
--- a/camel/camel-folder.c
+++ b/camel/camel-folder.c
@@ -50,6 +50,7 @@ static CamelFolderOpenMode _get_mode (CamelFolder *folder);
 static GList *_list_subfolders (CamelFolder *folder);
 static GList *_expunge (CamelFolder *folder);
 static CamelMimeMessage *_get_message (CamelFolder *folder, gint number);
+static gint _get_message_count (CamelFolder *folder);
 
 static void
 camel_folder_class_init (CamelFolderClass *camel_folder_class)
@@ -76,6 +77,8 @@ camel_folder_class_init (CamelFolderClass *camel_folder_class)
 	camel_folder_class->list_subfolders = _list_subfolders;
 	camel_folder_class->expunge = _expunge;
 	camel_folder_class->get_message = _get_message;
+	camel_folder_class->get_message_count = _get_message_count;
+
 	/* virtual method overload */
 }
 
@@ -383,19 +386,19 @@ _get_folder (CamelFolder *folder, const gchar *folder_name)
 	return new_folder;
 }
 
-/** 
- * camel_folder_get_folder: return the (sub)folder object that is specified.
- *
- * @folder : the folder
- * @folder_name: subfolder path. 
- *
+
+
+/**
+ * camel_folder_get_folder: return the (sub)folder object that is specified
+ * @folder: the folder
+ * @folder_name: subfolder path
+ * 
  * This method returns a folder objects. This folder
  * is necessarily a subfolder of the current folder. 
  * It is an error to ask a folder begining with the 
  * folder separator character.  
  * 
- * Return value: Required folder. NULL if the subfolder object
- *        could not be obtained
+ * Return value: Required folder. NULL if the subfolder object  could not be obtained
  **/
 CamelFolder *
 camel_folder_get_folder (CamelFolder *folder, gchar *folder_name)
@@ -758,3 +761,26 @@ camel_folder_get_message (CamelFolder *folder, gint number)
 	return CF_CLASS (folder)->get_message (folder, number);
 }
 
+
+static gint
+_get_message_count (CamelFolder *folder)
+{
+	return -1;
+}
+
+
+
+/**
+ * camel_folder_get_message_count: get the number of messages in the folder
+ * @folder: A CamelFolder object
+ * 
+ * Returns the number of messages in the folder.
+ * 
+ * Return value: the number of messages or -1 if unknown.
+ **/
+gint
+camel_folder_get_message_count (CamelFolder *folder)
+{
+	return CF_CLASS (folder)->get_message_count (folder);
+}
+
diff --git a/camel/camel-folder.h b/camel/camel-folder.h
index 6c17c331e2..2fd40a2591 100644
--- a/camel/camel-folder.h
+++ b/camel/camel-folder.h
@@ -99,6 +99,8 @@ typedef struct {
 	GList *  (*list_subfolders) (CamelFolder *folder);
 	GList *  (*expunge) (CamelFolder *folder);
 	CamelMimeMessage * (*get_message) (CamelFolder *folder, gint number);
+	gint   (*get_message_count) (CamelFolder *folder);
+	
 } CamelFolderClass;
 
 
diff --git a/camel/camel-service.c b/camel/camel-service.c
index c0f436bb89..0a27eb78fe 100644
--- a/camel/camel-service.c
+++ b/camel/camel-service.c
@@ -101,14 +101,15 @@ _connect (CamelService *service)
 }
 
 
+
 /**
- * camel_service_connect : connect to a service 
- *
+ * camel_service_connect:connect to a service 
+ * @service: CamelService object
+ * 
  * connect to the service using the parameters 
  * stored in the session it is initialized with
  * WARNING: session not implemented for the moment
- *
- * @service: object to connect to
+ * 
  **/
 void
 camel_service_connect (CamelService *service)
@@ -137,10 +138,10 @@ _connect_to_with_login_passwd (CamelService *service, gchar *host, gchar *login,
 
 /**
  * camel_service_connect_to_with_login_passwd: connect a service 
- * @service: the service to connect
+ * @service:  the service to connect
  * @host: host to connect to
  * @login: login to connect with
- * @passwd: password to connect with
+ * @passwd:  password to connect with
  * 
  * Connect to a service, but do not use the session
  * default parameters to retrieve server's address
@@ -154,21 +155,19 @@ camel_service_connect_to_with_login_passwd (CamelService *service, gchar *host,
 
 
 
+
 /**
- * _connect_to:login:password : connect to the specified address
- * 
- * Connect to the service, but do not use the session
- * default parameters to retrieve server's address
- *
- * @service: object to connect
- * @host: host to connect to
- * @login: user name used to log in
+ * _connect_to_with_login_passwd_port: connect to the specified address
+ * @service: service to connect
+ * @host:  host to connect to
+ * @login:  user name used to log in
  * @passwd: password used to log in
  * @port: port to connect to
- *
+ * 
+ * 
  **/
 static void
-_connect_to_with_login_passwd_port(CamelService *service, gchar *host, gchar *login, gchar *passwd, guint port)
+_connect_to_with_login_passwd_port (CamelService *service, gchar *host, gchar *login, gchar *passwd, guint port)
 {
     CSERV_CLASS(service)->set_connected(service, TRUE);
 }
@@ -176,11 +175,11 @@ _connect_to_with_login_passwd_port(CamelService *service, gchar *host, gchar *lo
 
 /**
  * camel_service_connect_to_with_login_passwd_port: connect a service 
- * @service: the service to connect
- * @host: host to connect to
- * @login: login to connect with
- * @passwd: password to connect with
- * @port: port to connect to 
+ * @service: service to connect
+ * @host:  host to connect to
+ * @login:  user name used to log in
+ * @passwd: password used to log in
+ * @port: port to connect to
  * 
  * Connect to a service, but do not use the session
  * default parameters to retrieve server's address
@@ -197,10 +196,11 @@ camel_service_connect_to_with_login_passwd_port (CamelService *service, gchar *h
 
 /**
  * _is_connected: test if the service object is connected
- *
- *
  * @service: object to test
- *  
+ * 
+ * 
+ * 
+ * Return value: 
  **/
 static gboolean
 _is_connected (CamelService *service)
@@ -210,13 +210,12 @@ _is_connected (CamelService *service)
 
 
 /**
- * camel_service_is_connected: test if a service object is connected
- *
- * @service:  the service
+ * camel_service_is_connected: test if the service object is connected
+ * @service: object to test
  * 
  * 
  * 
- * Return value: TRUE is the service is connected
+ * Return value: 
  **/
 gboolean
 camel_service_is_connected (CamelService *service)
@@ -225,16 +224,16 @@ camel_service_is_connected (CamelService *service)
 }
 
 
+
 /**
- * _set_connected: set the connected state
+ * _set_connected:set the connected state 
+ * @service: object to set the state of
+ * @state: connected/disconnected
  * 
  * This routine has to be called by providers to set the 
  * connection state, mainly when the service is disconnected
  * wheras the close() method has not been called.
- *
- * @service: object to set the state of
- * @state: connected/disconnected
- *  
+ * 
  **/
 static void
 _set_connected (CamelService *service, gboolean state)
@@ -251,6 +250,7 @@ _set_connected (CamelService *service, gboolean state)
  * This method merely returns the "url" field. Subclasses
  * may provide more active implementations.
  * 
+ * 
  * Return value: 
  **/
 static const gchar *
@@ -264,7 +264,7 @@ _get_url (CamelService *service)
  * @service: the service
  * 
  * returns the URL representing a service. For security reasons 
- * This routine may not always return the password.
+ * This routine may not always return the password. 
  * 
  * Return value: the url name
  **/
diff --git a/camel/camel-store.c b/camel/camel-store.c
index 56faca9a35..a6fb1a303e 100644
--- a/camel/camel-store.c
+++ b/camel/camel-store.c
@@ -104,8 +104,7 @@ camel_store_init (CamelStore *store, CamelSession *session, gchar *url_name)
 
 
 /**
- * init: method called by a session object to 
- * initialize a store object
+ * init: method called by a session object to  initialize a store object
  * @store: the store to initialize
  * @session: session which instantiates the store
  * @url_name: URL defining the store
@@ -130,8 +129,7 @@ _init (CamelStore *store, CamelSession *session, gchar *url_name)
 
 
 /** 
- * camel_store_set_separator: set the character which separates this folder 
- * path from the folders names in a lower level of hierarchy.
+ * camel_store_set_separator: set the character which separates this folder path from the folders names in a lower level of hierarchy.
  *
  * @store:
  * @sep:
@@ -155,12 +153,14 @@ _get_separator (CamelStore *store)
 }
 
 
-/** 
- * camel_store_get_separator: return the character which separates this folder 
- * path from the folders names in a lower level of hierarchy.
- *
+
+/**
+ * camel_store_get_separator: return the character which separates this folder path from the folders names in a lower level of hierarchy.
  * @store: store
- *
+ * 
+ * 
+ * 
+ * Return value: the separator
  **/
 gchar
 camel_store_get_separator (CamelStore *store)
@@ -183,6 +183,8 @@ _get_folder (CamelStore *store, const gchar *folder_name)
 
 /** 
  * camel_store_get_folder: return the folder corresponding to a path.
+ * @store: store
+ * @folder_name: name of the folder to get
  * 
  * Returns the folder corresponding to the path "name". 
  * If the path begins with the separator caracter, it 
@@ -193,8 +195,6 @@ _get_folder (CamelStore *store, const gchar *folder_name)
  * If it does not exist, you can create it with its 
  * "create" method.
  *
- * @store: store
- * @folder_name: name of the folder to get
  *
  * Return value: the folder
  **/
diff --git a/camel/gmime-content-field.c b/camel/gmime-content-field.c
index caa8237290..285926e702 100644
--- a/camel/gmime-content-field.c
+++ b/camel/gmime-content-field.c
@@ -91,8 +91,7 @@ gmime_content_field_set_parameter (GMimeContentField *content_field, const gchar
 
 
 /**
- * _print_parameter: print a parameter/value pair to a stream as 
- * described in RFC 2045
+ * _print_parameter: print a parameter/value pair to a stream as described in RFC 2045
  * @name: name of the parameter
  * @value: value of the parameter
  * @user_data: CamelStream object to write the text to.
@@ -213,8 +212,7 @@ gmime_content_field_get_parameter (GMimeContentField *content_field, const gchar
 
 
 /**
- * gmime_content_field_construct_from_string: construct a ContentType object
- * by parsing a string.
+ * gmime_content_field_construct_from_string: construct a ContentType object by parsing a string.
  *
  * @content_field: content type object to construct 
  * @string: string containing the content type field 
diff --git a/camel/providers/MH/camel-mh-store.c b/camel/providers/MH/camel-mh-store.c
index 0e382fa913..bb27e37620 100644
--- a/camel/providers/MH/camel-mh-store.c
+++ b/camel/providers/MH/camel-mh-store.c
@@ -90,7 +90,7 @@ camel_mh_store_get_type (void)
 
 
 
-/** These evil public functions are here for test only **/
+/* These evil public functions are here for test only */
 void 
 camel_mh_store_set_toplevel_dir (CamelMhStore *store, const gchar *toplevel)
 {
diff --git a/camel/url-util.c b/camel/url-util.c
index 43f51fe365..98eeaafddd 100644
--- a/camel/url-util.c
+++ b/camel/url-util.c
@@ -137,7 +137,7 @@ g_url_free (Gurl *url)
 
 /**** PARSING FUNCTIONS ****/
 
-/** So, yes, I must admit there would have been more elegant
+/* So, yes, I must admit there would have been more elegant
     ways to do this, but it works, and quite well :)  */