Re: New documentation style
- From: Philip Van Hoof <spam pvanhoof be>
- To: tinymail-devel-list gnome org
- Cc: j bitron c
- Subject: Re: New documentation style
- Date: Sun, 16 Dec 2007 19:26:40 +0100
Added some types.
On Sun, 2007-12-16 at 16:43 +0100, Philip Van Hoof wrote:
> Hf
>
> _______________________________________________
> tinymail-devel-list mailing list
> tinymail-devel-list gnome org
> http://mail.gnome.org/mailman/listinfo/tinymail-devel-list
--
Philip Van Hoof, freelance software developer
home: me at pvanhoof dot be
gnome: pvanhoof at gnome dot org
http://pvanhoof.be/blog
http://codeminded.be
Index: libtinymail/tny-folder-change.c
===================================================================
--- libtinymail/tny-folder-change.c (revision 3137)
+++ libtinymail/tny-folder-change.c (working copy)
@@ -17,6 +17,14 @@
* Boston, MA 02110-1301, USA.
*/
+/**
+ * TnyFolderChange:
+ *
+ * A delta of changes, used by #TnyFolderObserver
+ *
+ * free-functions: g_object_unref
+ **/
+
#include <config.h>
#include <tny-folder-change.h>
@@ -44,10 +52,15 @@
/**
* tny_folder_change_set_received_msg:
- * @self: a #TnyFolderChange instance
- * @msg: a #TnyMsg instance
+ * @self: a #TnyFolderChange
+ * @msg: a #TnyMsg
*
- * Set the message that got received
+ * Set the message that got received in @self. This is an internal function not
+ * intended for application developers to alter.
+ *
+ * since: 1.0
+ * complexity: high
+ * audience: tinymail-developer
**/
void
tny_folder_change_set_received_msg (TnyFolderChange *self, TnyMsg *msg)
@@ -64,14 +77,16 @@
/**
* tny_folder_change_get_received_msg:
- * @self: a #TnyFolderChange instance
+ * @self: a #TnyFolderChange
*
* Get the message that got received, if the change includes receiving a message.
* If no message was received, NULL will be returned. If not NULL, the returned
* value must be unreferenced after use.
*
- * Return value: the message that got received or NULL if no message was received
- * during this change.
+ * returns (null-ok) (caller-owns): received message or NULL
+ * since: 1.0
+ * complexity: high
+ * audience: application-developer
**/
TnyMsg *
tny_folder_change_get_received_msg (TnyFolderChange *self)
@@ -89,26 +104,33 @@
/**
* tny_folder_change_get_changed:
- * @self: a #TnyFolderChange instance
+ * @self: a #TnyFolderChange
*
* Get an enum with all the changed things
*
- * Return value: the changed-flags
+ * returns: the changed-flags
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
TnyFolderChangeChanged
tny_folder_change_get_changed (TnyFolderChange *self)
{
TnyFolderChangePriv *priv = TNY_FOLDER_CHANGE_GET_PRIVATE (self);
-
return priv->changed;
}
/**
* tny_folder_change_set_new_all_count:
- * @self: a #TnyFolderChange instance
- * @new_all_count: the new all count of the folder
+ * @self: a #TnyFolderChange
+ * @new_all_count: all count
*
- * Set the all count of the changeset
+ * Set the all count of @self. This is an internal function not intended for
+ * application developers to alter.
+ *
+ * since: 1.0
+ * complexity: high
+ * audience: tinymail-developer
**/
void
tny_folder_change_set_new_all_count (TnyFolderChange *self, guint new_all_count)
@@ -125,10 +147,15 @@
/**
* tny_folder_change_set_new_unread_count:
- * @self: a #TnyFolderChange instance
- * @new_unread_count: the new unread count of the folder
+ * @self: a #TnyFolderChange
+ * @new_unread_count: unread count
*
- * Set the unread count of the changeset
+ * Set the unread count. This is an internal function not intended for
+ * application developers to alter.
+ *
+ * since: 1.0
+ * complexity: high
+ * audience: tinymail-developer
**/
void
tny_folder_change_set_new_unread_count (TnyFolderChange *self, guint new_unread_count)
@@ -146,42 +173,51 @@
/**
* tny_folder_change_get_new_unread_count:
- * @self: a #TnyFolderChange instance
+ * @self: a #TnyFolderChange
*
- * Get the unread count of the changeset
+ * Get the unread count of @self.
*
- * Return value: the new unread-count
+ * returns: unread count
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
guint
tny_folder_change_get_new_unread_count (TnyFolderChange *self)
{
TnyFolderChangePriv *priv = TNY_FOLDER_CHANGE_GET_PRIVATE (self);
-
return priv->new_unread_count;
}
/**
* tny_folder_change_get_new_all_count:
- * @self: a #TnyFolderChange instance
+ * @self: a #TnyFolderChange
*
- * Get the all count of the changeset
+ * Get the all count of @self
*
- * Return value: the new all-count
+ * returns: all count
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
guint
tny_folder_change_get_new_all_count (TnyFolderChange *self)
{
TnyFolderChangePriv *priv = TNY_FOLDER_CHANGE_GET_PRIVATE (self);
-
return priv->new_all_count;
}
/**
* tny_folder_change_add_added_header:
- * @self: a #TnyFolderChange instance
- * @header: the header to add to the changeset
+ * @self: a #TnyFolderChange
+ * @header: a #TnyHeader
*
- * Add @header to the changeset of added headers
+ * Add @header to @self. This is an internal function not intended for
+ * application developers to alter.
+ *
+ * since: 1.0
+ * complexity: high
+ * audience: tinymail-developer
**/
void
tny_folder_change_add_added_header (TnyFolderChange *self, TnyHeader *header)
@@ -202,9 +238,14 @@
/**
* tny_folder_change_add_expunged_header:
* @self: a #TnyFolderChange instance
- * @header: the header to add to the changeset
+ * @header: a #TnyHeader
*
- * Add @header to the changeset of expunged headers
+ * Add @header to @self. This is an internal function not intended for
+ * application developers to alter.
+ *
+ * since: 1.0
+ * complexity: high
+ * audience: tinymail-developer
**/
void
tny_folder_change_add_expunged_header (TnyFolderChange *self, TnyHeader *header)
@@ -224,10 +265,14 @@
/**
* tny_folder_change_get_added_headers:
- * @self: a #TnyFolderChange instance
- * @headers: the #TnyList where the added headers will be put it
+ * @self: a #TnyFolderChange
+ * @headers: a #TnyList where the added headers will be prepended to
*
- * Get the added headers in this changeset
+ * Get the added headers in @self.
+ *
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
void
tny_folder_change_get_added_headers (TnyFolderChange *self, TnyList *headers)
@@ -265,10 +310,14 @@
/**
* tny_folder_change_get_expunged_headers:
- * @self: a #TnyFolderChange instance
- * @headers: the #TnyList where the removed headers will be put it
+ * @self: a #TnyFolderChange
+ * @headers: a #TnyList where the removed headers will be prepended to
*
- * Get the removed headers in this changeset
+ * Get the removed headers in @self.
+ *
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
void
tny_folder_change_get_expunged_headers (TnyFolderChange *self, TnyList *headers)
@@ -305,9 +354,14 @@
/**
* tny_folder_change_reset:
- * @self: a #TnyFolderChange instance
+ * @self: a #TnyFolderChange
*
- * Reset the state of @self
+ * Reset the state of @self. This is an internal function not intended for
+ * application developers to alter.
+ *
+ * since: 1.0
+ * complexity: high
+ * audience: tinymail-developer
**/
void
tny_folder_change_reset (TnyFolderChange *self)
@@ -334,15 +388,18 @@
/**
* tny_folder_change_get_rename:
* @self: a #TnyFolderChange instance
- * @oldname: a pointer to a string (by reference)
+ * @oldname (null-ok) (out): a byref string or NULL
*
* Get the new name of the folder in case of a rename. This will return NULL
- * of no rename happened. You can pass a pointer if you need the old folder
- * name too.
+ * if no rename happened. You can pass a pointer if you need the old name of
+ * the folder too, else pass NULL.
*
- * You should not free the returned value nor the @oldname pointer.
+ * You must not free the returned value nor the @oldname pointer.
*
- * Return value: The new folder name or NULL
+ * return (null-ok): The new folder name or NULL
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
const gchar *
tny_folder_change_get_rename (TnyFolderChange *self, const gchar **oldname)
@@ -370,8 +427,12 @@
* @newname: the new name of the folder
*
* Mark the change in such a way that the user can know that a rename has
- * happened. The TnyFolderChange will copy your @newname internally, so you
- * can do whatever you want with what you passed afterwards (like freeing it).
+ * happened. This is an internal function not intended for application
+ * developers to alter.
+ *
+ * since: 1.0
+ * complexity: high
+ * audience: tinymail-developer
**/
void
tny_folder_change_set_rename (TnyFolderChange *self, const gchar *newname)
@@ -389,11 +450,11 @@
/**
* tny_folder_change_new:
- * @folder: a #TnyFolder instance
+ * @folder: a #TnyFolder
*
* Creates a changeset for @folder
*
- * Return value: a new #TnyFolderChange instance
+ * returns (caller-owns): a new #TnyFolderChange instance
**/
TnyFolderChange*
tny_folder_change_new (TnyFolder *folder)
@@ -414,7 +475,7 @@
* Get the folder of @self. The return value of this method must be unreferenced
* after use.
*
- * Return value: the #TnyFolder related to this changeset
+ * returns (caller-owns): the #TnyFolder of this changeset
**/
TnyFolder*
tny_folder_change_get_folder (TnyFolderChange *self)
@@ -537,7 +598,7 @@
*
* GType system helper function
*
- * Return value: a GType
+ * returns: a #GType
**/
GType
tny_folder_change_changed_get_type (void)
Index: libtinymail/tny-folder-monitor.c
===================================================================
--- libtinymail/tny-folder-monitor.c (revision 3137)
+++ libtinymail/tny-folder-monitor.c (working copy)
@@ -17,8 +17,18 @@
* Boston, MA 02110-1301, USA.
*/
+/**
+ * TnyFolderMonitor:
+ *
+ * A publisher subscriber that subscribes as #TnyFolderObserver to a folder,
+ * and publishes to a list of #TnyList instances.
+ *
+ * free-function: g_object_unref
+ **/
+
+#include <config.h>
+
#include <string.h>
-#include <config.h>
#include <glib.h>
#include <glib/gi18n-lib.h>
@@ -44,13 +54,16 @@
/**
* tny_folder_monitor_add_list:
- * @self: a #TnyFolderChange instance
- * @list: a #TnyList instance
+ * @self: a #TnyFolderChange
+ * @list: a #TnyList
*
* Add @list to the registered lists that are interested in changes. @list will
- * remain referenced until it's unregisterd using tny_folder_monitor_remove_list
+ * remain referenced until it's unregisterd using tny_folder_monitor_remove_list()
* or until @self is finalized.
*
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
void
tny_folder_monitor_add_list (TnyFolderMonitor *self, TnyList *list)
@@ -75,12 +88,15 @@
/**
* tny_folder_monitor_remove_list:
- * @self: a #TnyFolderChange instance
- * @list: a #TnyList instance
+ * @self: a #TnyFolderChange
+ * @list: a #TnyList
*
* Remove @list from the lists that are interested in changes. This will remove
- * the reference that got added when you ussed the tny_folder_monitor_add_list.
+ * the reference that got added when the tny_folder_monitor_add_list() was used.
*
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
void
tny_folder_monitor_remove_list (TnyFolderMonitor *self, TnyList *list)
@@ -105,11 +121,14 @@
/**
* tny_folder_monitor_poke_status
- * @self: a #TnyFolderMonitor instance
+ * @self: a #TnyFolderMonitor
*
- * Trigger the poke method on the folder instance being monitored.
- * Also take a look at tny_folder_poke_status in #TnyFolder.
+ * Invoke the poke method on the folder instance being monitored.
+ * Also take a look at tny_folder_poke_status() in #TnyFolder.
*
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
void
tny_folder_monitor_poke_status (TnyFolderMonitor *self)
@@ -282,17 +301,15 @@
/**
* tny_folder_monitor_stop:
- * @self: a #TnyFolderMonitor instance
+ * @self: a #TnyFolderMonitor
*
- * Stop monitoring the folder. At some point in time you must perform method
- * after you used tny_folder_monitor_start (for example before unreferencing
- * @self).
+ * Stop monitoring the folder. At some point in time you must perform this
+ * method. But after you used tny_folder_monitor_start() (use it for example
+ * just before unreferencing @self).
*
- * The reason for that is that unless you stop @self, it would still have a
- * reference being held by the #TnyFolder instance being monitored. By stopping
- * this monitor, you explicitly ask that folder instance to unregister @self as
- * an observer. And by that loosing that reference too.
- *
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
void
tny_folder_monitor_stop (TnyFolderMonitor *self)
@@ -311,16 +328,15 @@
/**
* tny_folder_monitor_start:
- * @self: a #TnyFolderMonitor instance
+ * @self: a #TnyFolderMonitor
*
* Start monitoring the folder. The starting of a monitor implies that @self
- * will become an observer of the folder instance. This adds a reference to @self
- * that at some point in time must be removed using tny_folder_monitor_stop.
+ * will become an observer of the folder instance. At some point in time you
+ * must use tny_folder_monitor_stop() to stop monitoring the folder.
*
- * This means that if you start the monitor, you must also at some point stop it.
- *
- * Keep this in mind: monitoring means that registered lists are kept alive. A
- * list that is alive means that it's consuming memory!
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
void
tny_folder_monitor_start (TnyFolderMonitor *self)
@@ -339,11 +355,11 @@
/**
* tny_folder_monitor_new:
- * @folder: a #TnyFolder instance
+ * @folder: a #TnyFolder
*
* Creates a folder monitor for @folder
*
- * Return value: a new #TnyFolderMonitor instance
+ * returns (caller-owns): a new #TnyFolderMonitor instance
**/
TnyFolderObserver*
tny_folder_monitor_new (TnyFolder *folder)
Index: libtinymail/tny-account-store.c
===================================================================
--- libtinymail/tny-account-store.c (revision 3137)
+++ libtinymail/tny-account-store.c (working copy)
@@ -17,6 +17,15 @@
* Boston, MA 02110-1301, USA.
*/
+
+/**
+ * TnyAccountStore:
+ *
+ * A account store, holding a list of accounts
+ *
+ * free-function: g_object_unref
+ */
+
#include <config.h>
#ifdef DBC
@@ -35,21 +44,16 @@
/**
* tny_account_store_find_account:
- * @self: a #TnyAccountStore object
+ * @self: a #TnyAccountStore
* @url_string: the url-string of the account to find
*
- * Try to find the account in @self that corresponds to @url_string. If this
- * method does not return NULL, the returned value is the found account and
- * must be unreferenced after use.
+ * Try to find the first account in account store @self that corresponds to
+ * @url_string. If found, the returned value must be unreferenced.
*
- * Implementors: when implementing a platform-specific library, you must
- * implement this method. Let it return the account that corresponds to
- * @url_string or let it return NULL. Also see tny_account_matches_url_string
- * at #TnyAccount.
- *
- * This method can be used to resolve url-strings to #TnyAccount instances.
- *
- * Return value: the found account or NULL.
+ * returns (null-ok) (caller-owns): the found account or NULL
+ * since: 1.0
+ * audience: application-developer
+ * complexity: high
**/
TnyAccount*
tny_account_store_find_account (TnyAccountStore *self, const gchar *url_string)
@@ -60,7 +64,7 @@
g_assert (TNY_IS_ACCOUNT_STORE (self));
g_assert (url_string);
g_assert (strlen (url_string) > 0);
- g_assert (strstr (url_string, "://"));
+ g_assert (strstr (url_string, ":"));
g_assert (TNY_ACCOUNT_STORE_GET_IFACE (self)->find_account_func != NULL);
#endif
@@ -78,28 +82,22 @@
/**
* tny_account_store_alert:
- * @self: a #TnyAccountStore object
- * @account: The account (This is NULL sometimes for some current implementations).
- * @type: the message type (severity)
+ * @self: a #TnyAccountStore
+ * @account (null-ok): The account or NULL
+ * @type: alert type
* @question: whether or not this is a question
- * @error: A GError, of domain TNY_ACCOUNT_ERROR or TNY_ACCOUNT_STORE_ERROR,
- * which should be used to determine what to show to the user.
+ * @error: A #GError with the alert
*
- * This jump-to-the-ui method implements showing a message dialog appropriate
+ * This callback method must implements showing a message dialog appropriate
* for the @error and @type as message type. It will return TRUE if the reply
* was affirmative or FALSE if not.
*
- * You must not try reconnecting in the implementation of this method.
+ * The two possible answers that must be supported are "Yes" and "No" which must
+ * result in a TRUE or a FALSE return value, though your implementation should
+ * attempt to use explicit button names such as "Accept Certificate" and
+ * "Reject Certificate". Likewise, the dialog should be arranged according to
+ * the user interface guidelines of your target platform.
*
- * Implementors: when implementing a platform-specific library, you must
- * implement this method. For example in GTK+ by using the #GtkDialog API. The
- * implementation will, for example, be used to ask the user about accepting SSL
- * certificates. The two possible answers that must be supported are
- * "Yes" and "No" which must result in a TRUE or a FALSE return value, though
- * your implementation should attempt to use explicit button names such as
- * "Accept Certificate" and "Reject Certificate". Likewise, the dialog should be
- * arranged according the the user interface guidelines of your target platform.
- *
* Although there is a @question parameter, there is not always certainty about
* whether or not the warning actually is a question. It's save to say, however
* that in case @question is FALSE, that the return value of the function's
@@ -148,7 +146,10 @@
* }
* </programlisting></informalexample>
*
- * Return value: Whether the user pressed Ok/Yes (TRUE) or Cancel/No (FALSE)
+ * returns: Affirmative = TRUE, Negative = FALSE
+ * since: 1.0
+ * audience: platform-developer, application-developer, type-implementer
+ * complexity: high
**/
gboolean
tny_account_store_alert (TnyAccountStore *self, TnyAccount *account, TnyAlertType type, gboolean question, const GError *error)
@@ -170,17 +171,15 @@
/**
* tny_account_store_get_device:
- * @self: a #TnyAccountStore object
+ * @self: a #TnyAccountStore
*
- * This method returns a #TnyDevice instance. You must unreference the return
- * value after use.
+ * This method returns the #TnyDevice instance used by #TnyAccountStore @self. You
+ * must unreference the return value after use.
*
- * Implementors: when implementing a platform-specific library, you must
- * implement this method by letting it return a #TnyDevice instance. You must
- * add a reference count before returning.
- *
- * Return value: the device attached to this account store
- *
+ * returns (caller-owns): the device used by @self
+ * since: 1.0
+ * audience: application-developer
+ * complexity: low
**/
TnyDevice*
tny_account_store_get_device (TnyAccountStore *self)
@@ -204,20 +203,16 @@
/**
* tny_account_store_get_cache_dir:
- * @self: a #TnyAccountStore object
+ * @self: a #TnyAccountStore
*
- * Get the local path that will be used for storing the disk cache
+ * Returns the path that will be used for storing cache. Note that the callers
+ * of this method will not free up the result. The implementation of
+ * #TnyAccountStore @self is responsible for freeing up.
*
- * Implementors: when implementing a platform-specific library, you must
- * implement this method. You can for example let it return the path to some
- * folder in $HOME on the file system.
- *
- * Note that the callers of this method will not free the result. The
- * implementor of a #TnyAccountStore is responsible for freeing it up. For
- * example when destroying @self (in its finalize method).
- *
- * Return value: the local path that will be used for storing the disk cache
- *
+ * returns: cache's path
+ * since: 1.0
+ * audience: platform-developer, type-implementer
+ * complexity: low
**/
const gchar*
tny_account_store_get_cache_dir (TnyAccountStore *self)
@@ -242,12 +237,11 @@
/**
* tny_account_store_get_accounts:
- * @self: a #TnyAccountStore object
- * @list: a #TnyList instance that will be filled with #TnyAccount instances
- * @types: a #TnyGetAccountsRequestType that describes which account types are needed
+ * @self: a #TnyAccountStore
+ * @list: a #TnyList that will be filled with #TnyAccount instances
+ * @types: a #TnyGetAccountsRequestType that indicates which account types are wanted
*
- * Get a read-only list of accounts in the store. You must not change @list
- * except for referencing and unreferencing.
+ * Get a list of accounts in the account store @self.
*
* Example:
* <informalexample><programlisting>
@@ -265,28 +259,20 @@
* g_object_unref (G_OBJECT (list));
* </programlisting></informalexample>
*
- * Implementors: when implementing a platform-specific library, you must
- * implement this method.
+ * When implementing this API it is allowed but not required to cache the list.
+ * If you are implementing an account store for #TnyCamelAccount account
+ * instances, register the created accounts with a #TnySessionCamel instance
+ * using the API tny_session_camel_set_current_accounts right after creating
+ * the accounts for the first time.
*
- * It is allowed to cache the list (but not required). If you are implementing
- * an account store for account implementations from libtinymail-camel, you must
- * register the created accounts with a #TnySessionCamel instance using the
- * libtinymail-camel specific tny_session_camel_set_current_accounts API.
+ * If you use the #TnySessionCamel to register accounts, register each account
+ * using tny_camel_account_set_session and after registering your last account
+ * use the API tny_session_camel_set_initialized
*
- * If you use the #TnySessionCamel to register accounts, you must after
- * registering your last initial account call the tny_session_camel_set_initialized
- * API.
- *
- * The implementation must fillup @list with available accounts. Note that if
+ * The method must fill up @list with available accounts. Note that if
* you cache the list, you must add a reference to each account added to the
- * list (else they will be unreferenced and if the reference count would reach
- * zero, an account would no longer be correctly cached).
+ * list.
*
- * With libtinymail-camel each created account must also be informed about the
- * #TnySessionCamel instance being used. Read more about this at
- * tny_camel_account_set_session of the libtinymail-camel specific
- * #TnyCamelAccount.
- *
* There are multiple samples of #TnyAccountStore implementations in
* libtinymail-gnome-desktop, libtinymail-olpc, libtinymail-gpe,
* libtinymail-maemo and tests/shared/account-store.c which is being used by
@@ -294,7 +280,7 @@
*
* The get_pass and forget_pass functionality of the example below is usually
* implemented by utilizing a #TnyPasswordGetter that is returned by the
- * #TnyPlatformFactory, that is usually available from the #TnyAccountStore.
+ * #TnyPlatformFactory.
*
* Example (that uses a cache):
* <informalexample><programlisting>
@@ -346,6 +332,10 @@
* tny_session_camel_set_initialized (session);
* }
* </programlisting></informalexample>
+ *
+ * since: 1.0
+ * audience: platform-developer, application-developer, type-implementer
+ * complexity: high
**/
void
tny_account_store_get_accounts (TnyAccountStore *self, TnyList *list, TnyGetAccountsRequestType types)
@@ -378,7 +368,11 @@
* @self: the object on which the signal is emitted
* @user_data: user data set when the signal handler was connected.
*
- * Emitted when the store starts trying to connect the accounts
+ * Emitted when the store starts trying to connect the accounts. Usage of this
+ * signal is not recommended as it's a candidate for API changes.
+ *
+ * since: 1.0
+ * complexity: high
*/
tny_account_store_signals[TNY_ACCOUNT_STORE_CONNECTING_STARTED] =
g_signal_new ("connecting_started",
@@ -400,7 +394,8 @@
*
* GType system helper function
*
- * Return value: a GType
+ * returns: a #GType
+ * since: 1.0
**/
GType
tny_account_store_get_type (void)
@@ -435,7 +430,8 @@
*
* GType system helper function
*
- * Return value: a GType
+ * returns: a #GType
+ * since: 1.0
**/
GType
tny_alert_type_get_type (void)
@@ -458,7 +454,8 @@
*
* GType system helper function
*
- * Return value: a GType
+ * returns: a #GType
+ * since: 1.0
**/
GType
tny_get_accounts_request_type_get_type (void)
@@ -483,7 +480,8 @@
*
* GType system helper function
*
- * Return value: a GType
+ * returns: a #GType
+ * since: 1.0
**/
GType
tny_account_store_signal_get_type (void)
Index: libtinymail/tny-iterator.c
===================================================================
--- libtinymail/tny-iterator.c (revision 3137)
+++ libtinymail/tny-iterator.c (working copy)
@@ -17,6 +17,14 @@
* Boston, MA 02110-1301, USA.
*/
+/**
+ * TnyIterator:
+ *
+ * A position indicator for a #TnyList
+ *
+ * free-function: g_object_unref
+ **/
+
#include <config.h>
#include <tny-iterator.h>
@@ -24,10 +32,13 @@
/**
* tny_iterator_next:
- * @self: A #TnyIterator instance
+ * @self: A #TnyIterator
*
* Moves the iterator to the next node
*
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer, type-implementer
**/
void
tny_iterator_next (TnyIterator *self)
@@ -44,10 +55,13 @@
/**
* tny_iterator_prev:
- * @self: A #TnyIterator instance
+ * @self: A #TnyIterator
*
* Moves the iterator to the previous node
*
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer, type-implementer
**/
void
tny_iterator_prev (TnyIterator *self)
@@ -65,10 +79,13 @@
/**
* tny_iterator_first:
- * @self: A #TnyIterator instance
+ * @self: A #TnyIterator
*
* Moves the iterator to the first node
*
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer, type-implementer
**/
void
tny_iterator_first (TnyIterator *self)
@@ -85,11 +102,14 @@
/**
* tny_iterator_nth:
- * @self: A #TnyIterator instance
+ * @self: A #TnyIterator
* @nth: The nth position
*
* Moves the iterator to the nth node
*
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer, type-implementer
**/
void
tny_iterator_nth (TnyIterator *self, guint nth)
@@ -109,12 +129,14 @@
* tny_iterator_get_current:
* @self: A #TnyIterator instance
*
- * Does not move the iterator. Returns the object at the current position. If
- * there's no current position, this method returns NULL. If not NULL, the
- * returned value must be unreferenced after use.
+ * Returns the object at the current position. If there's no current position,
+ * this method returns NULL. If not NULL, the returned value must be unreferenced
+ * after use.
*
- * Return value: the currect object or NULL
- *
+ * returns (null-ok) (caller-owns) (type-parameter G): the currect object or NULL
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer, type-implementer
**/
GObject*
tny_iterator_get_current (TnyIterator *self)
@@ -139,7 +161,7 @@
/**
* tny_iterator_is_done:
- * @self: A #TnyIterator instance
+ * @self: A #TnyIterator
*
* Does the iterator point to some valid list item? You can use this property
* to make loops like:
@@ -155,12 +177,14 @@
* g_object_unref (cur);
* tny_iterator_next (iter);
* }
- * g_object_unref (G_OBJECT (iter));
- * g_object_unref (G_OBJECT (list));
+ * g_object_unref (iter);
+ * g_object_unref (list);
* </programlisting></informalexample>
*
- * Return value: TRUE if it points to a valid list item, FALSE otherwise
- *
+ * returns: TRUE if it points to a valid list item, FALSE otherwise
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer, type-implementer
**/
gboolean
tny_iterator_is_done (TnyIterator *self)
@@ -177,14 +201,16 @@
/**
* tny_iterator_get_list:
- * @self: A #TnyIterator instance
+ * @self: A #TnyIterator
*
- * Does not move the iterator. Returns the list of which this iterator is an
- * iterator. The returned list object should be unreferenced after use. Remember
- * when using this property that lists shouldn't change while iterating them.
+ * Returns the list of which this iterator is an iterator. The returned list
+ * object should be unreferenced after use. Remember when using this property
+ * that lists shouldn't change while iterating them.
*
- * Return value: The #TnyList instance being iterated
- *
+ * returns (caller-owns): The #TnyList being iterated
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer, type-implementer
**/
TnyList*
tny_iterator_get_list (TnyIterator *self)
Index: libtinymail/tny-combined-account.c
===================================================================
--- libtinymail/tny-combined-account.c (revision 3141)
+++ libtinymail/tny-combined-account.c (working copy)
@@ -17,6 +17,14 @@
* Boston, MA 02110-1301, USA.
*/
+/**
+ * TnyCombinedAccount:
+ *
+ * A combined account
+ *
+ * free-function: g_object_unref
+ */
+
#include <config.h>
#include <glib.h>
#include <glib/gi18n-lib.h>
@@ -369,19 +377,22 @@
/**
* tny_combined_account_new:
- * @ta: A #TnyTransportAccount instance
- * @sa: a #TnyStoreAccount instance
+ * @ta: A #TnyTransportAccount
+ * @sa: a #TnyStoreAccount
*
* Create a decorator for @ta, in case the tny_transport_account_send is used,
- * and for @sa in case any other method of either TnyFolderStore, TnyAccount
- * or TnyStoreAccount is used.
+ * and for @sa in case a method of either #TnyFolderStore, #TnyAccount or
+ * #TnyStoreAccount is used.
*
* Note though that you must not use instances created by this constructor for
* either setting or getting members of the #TnyAccount type. You must get the
- * actual instances to read this from using either
- * tny_combined_account_get_transport_account or tny_combined_account_get_store_account.
+ * actual instances to read these properties.
*
- * Return value: A new account instance that decorates both @ta and @sa
+ * returns (caller-owns): A new account instance that decorates both @ta and @sa
+ *
+ * since: 1.0
+ * complexity: high
+ * audience: application-developer
**/
TnyAccount *
tny_combined_account_new (TnyTransportAccount *ta, TnyStoreAccount *sa)
@@ -401,12 +412,15 @@
/**
* tny_combined_account_get_transport_account:
- * @self: a #TnyCombinedAccount instance
+ * @self: a #TnyCombinedAccount
*
* Get the transport account that is being decorated by @self. You must unreference
* the returned value if not needed anymore.
*
- * Return value: the transport account being decorated
+ * returns (caller-owns): the transport account in @self
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
TnyTransportAccount*
tny_combined_account_get_transport_account (TnyCombinedAccount *self)
@@ -418,12 +432,15 @@
/**
* tny_combined_account_get_store_account:
- * @self: a #TnyCombinedAccount instance
+ * @self: a #TnyCombinedAccount
*
* Get the store account that is being decorated by @self. You must unreference
* the returned value if not needed anymore.
*
- * Return value: the store account being decorated
+ * returns (caller-owns): the store account in @self
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
TnyStoreAccount*
tny_combined_account_get_store_account (TnyCombinedAccount *self)
Index: libtinymail/tny-error.c
===================================================================
--- libtinymail/tny-error.c (revision 3137)
+++ libtinymail/tny-error.c (working copy)
@@ -19,15 +19,12 @@
#include <tny-error.h>
-
-/* TODO: These get_type() functions should be generated, as in GTK+, gnome-vfs, etc. */
-
/**
* tny_error_domain_get_type:
*
* GType system helper function
*
- * Return value: a GType
+ * returns: a #GType
**/
GType
tny_error_domain_get_type (void)
@@ -54,7 +51,7 @@
*
* GType system helper function
*
- * Return value: a GType
+ * returns: a #GType
**/
GType
tny_error_get_type (void)
@@ -63,9 +60,6 @@
if (etype == 0) {
static const GEnumValue values[] = {
-
-
-
{ TNY_ERROR_UNSPEC, "TNY_ERROR_UNSPEC", "error_unspec" },
{ TNY_FOLDER_ERROR_SYNC, "TNY_FOLDER_ERROR_SYNC", "folder_error_sync" },
{ TNY_FOLDER_ERROR_REMOVE_MSG, "TNY_FOLDER_ERROR_REMOVE_MSG", "folder_error_remove_msg" },
Index: libtinymail/tny-device.c
===================================================================
--- libtinymail/tny-device.c (revision 3137)
+++ libtinymail/tny-device.c (working copy)
@@ -17,6 +17,14 @@
* Boston, MA 02110-1301, USA.
*/
+/**
+ * TnyDevice:
+ *
+ * A device, with online and offline state
+ *
+ * free-function: g_object_unref
+ */
+
#include <config.h>
#include <tny-device.h>
@@ -25,19 +33,25 @@
/**
* tny_device_reset:
- * @self: a #TnyDevice object
+ * @self: a #TnyDevice
*
- * Reset the status (unforce the status).
+ * Reset the status of @self, unforce the status.
*
- * This reverses the effects of tny_device_force_online() or
- * tny_device_force_offline(), so that future changes of connection status will
- * cause the connection_changed signal to be emitted, and tny_device_is_online()
+ * This reverses the effects of tny_device_force_online and
+ * tny_device_force_offline. Future changes of connection status will
+ * cause the connection_changed signal to be emitted, and tny_device_is_online
* will return a correct value.
*
- * The connection_changed signal will be emitted if this tny_device_is_online()
- * to return a different value than before, for instance if the network
- * connection has actually become available or unavailable while the status was
- * forced.
+ * The connection_changed signal will be emitted if to return a different value
+ * than before, for instance if the network connection has actually become
+ * available or unavailable while the status was forced. For example in case
+ * the forced state was offline, and after reset the actual state is online. Or
+ * in case the forced state was online, and after reset the actual state is
+ * offline.
+ *
+ * since: 1.0
+ * complexity: high
+ * audience: platform-developer, type-implementer
**/
void
tny_device_reset (TnyDevice *self)
@@ -57,21 +71,21 @@
/**
* tny_device_force_online:
- * @self: a #TnyDevice object
+ * @self: a #TnyDevice
*
* Force online status, so that tny_device_is_online() returns TRUE, regardless
* of whether there is an actual network connection. The connection_changed
- * signal will be emitted if the online status is changed by this function,
- * but note if a real network connection is made or lost later, the
- * connection_changed signal will not be emitted again, and tny_device_is_online()
- * will continue to return TRUE;
+ * signal will be emitted if the returned value of tny_device_is_online()
+ * changed by this function.
*
- * This might be used on platforms that cannot detect whether a network
- * connection exists.
+ * This can be used on platforms that cannot detect whether a network connection
+ * exists. This will usually not attempt to make a real network connection.
*
- * This will usually not attempt to make a real network connection.
+ * See also tny_device_force_offline() and tny_device_reset().
*
- * See also tny_device_force_offline() and tny_device_reset().
+ * since: 1.0
+ * complexity: high
+ * audience: platform-developer, type-implementer
**/
void
tny_device_force_online (TnyDevice *self)
@@ -92,23 +106,19 @@
/**
* tny_device_force_offline:
- * @self: a #TnyDevice object
+ * @self: a #TnyDevice
*
* Force offline status, so that tny_device_is_online() returns FALSE, regardless
- * of whether there is an actual network connection. The connection_changed
- * signal will be emitted if the online status is changed by this function, but
- * note if a real network connection is made or lost later, the connection_changed
- * signal will not be emitted again, and tny_device_is_online() will continue to
- * return FALSE;
+ * of whether there is an actual network connection. The connection_changed
+ * signal will be emitted if the returned value of tny_device_is_online()
+ * changed by this function.
*
- * This might be used to mark a device as offline if the connection is partly
- * unusable due to some specific error, such as a failure to access a server or
- * to use a particular port, or if the user specifically chose "offline mode".
- * It might also be used on platforms that cannot detect whether a network
- * connection exists.
+ * This can be used to mark a device as offline if the connection is unusable
+ * due to some specific error, such as a failure to access a server or to use
+ * a particular port, or if the user specifically chose "offline mode". It can
+ * also be used on platforms that cannot detect whether a network connection
+ * exists. This will usually not attempt to disconnect a real network connection.
*
- * This will usually not attempt to disconnect a real network connection.
- *
* Example:
* <informalexample><programlisting>
* TnyDevice *device = ...
@@ -119,6 +129,10 @@
* </programlisting></informalexample>
*
* See also tny_device_force_online() and tny_device_reset().
+ *
+ * since: 1.0
+ * complexity: high
+ * audience: platform-developer, type-implementer
**/
void
tny_device_force_offline (TnyDevice *self)
@@ -139,22 +153,26 @@
/**
* tny_device_is_online:
- * @self: a #TnyDevice object
+ * @self: a #TnyDevice
*
+ * Request the current state of @self. In case of forced online, this function
+ * returns TRUE. In case of forced offline, this function returns FALSE. In case
+ * of online, this function returns TRUE. In case of offline, this function
+ * returns FALSE.
+ *
* Example:
* <informalexample><programlisting>
- * static void
- * connection_changed (TnyDevice *device, gboolean online, gpointer user_data)
- * {
- * if (!online && tny_device_is_online (device))
- * g_print ("Something is wrong\n");
- * }
* TnyDevice *device = ...
- * g_signal_connect (G_OBJECT (device), "connection_changed",
- * G_CALLBACK (connection_changed), self);
+ * tny_device_force_online (device);
+ * if (!tny_device_is_online (device))
+ * g_print ("Something is wrong\n");
+ * tny_device_reset (device);
* </programlisting></informalexample>
*
- * Return value: Whether the device is online
+ * returns: TRUE if online or forced online, FALSE if offline or forced offline
+ * since: 1.0
+ * complexity: low
+ * audience: platform-developer, type-implementer
**/
gboolean
tny_device_is_online (TnyDevice *self)
@@ -192,9 +210,10 @@
* while the status is forced with tny_device_force_online() or
* tny_device_force_offline().
*
- * Implementors must make sure that the emissions of this signal always
- * happen in the mainloop.
- */
+ * since: 1.0
+ * complexity: low
+ * audience: platform-developer, type-implementer
+ **/
tny_device_signals[TNY_DEVICE_CONNECTION_CHANGED] =
g_signal_new ("connection_changed",
TNY_TYPE_DEVICE,
@@ -245,7 +264,7 @@
*
* GType system helper function
*
- * Return value: a GType
+ * returns: a #GType
**/
GType
tny_device_signal_get_type (void)
Index: libtinymail/tny-folder.c
===================================================================
--- libtinymail/tny-folder.c (revision 3137)
+++ libtinymail/tny-folder.c (working copy)
@@ -17,6 +17,14 @@
* Boston, MA 02110-1301, USA.
*/
+/**
+ * TnyFolder:
+ *
+ * A folder, or a mailbox depending on what you prefer to call it
+ *
+ * free-function: g_object_unref
+ */
+
#include <config.h>
#ifdef DBC
@@ -36,11 +44,14 @@
/**
* tny_folder_get_caps:
- * @self: a #TnyFolder object
+ * @self: a #TnyFolder
*
* Get a few relevant capabilities of @self.
*
- * Return value: The capabilities of the folder
+ * returns: The capabilities of the folder
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
TnyFolderCaps
tny_folder_get_caps (TnyFolder *self)
@@ -55,7 +66,7 @@
/**
* tny_folder_get_url_string:
- * @self: a #TnyFolder object
+ * @self: a #TnyFolder
*
* Get the url_string of @self or NULL if it's impossible to determine the url
* string of @self. If not NULL, the returned value must be freed after use.
@@ -64,7 +75,10 @@
* this: imap://server/INBOX/folder. Note that it doesn't necessarily contain
* the password of the IMAP account but can contain it.
*
- * Return value: The url string or NULL.
+ * returns (null-ok) (caller-owns): The url string or NULL.
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
gchar*
tny_folder_get_url_string (TnyFolder *self)
@@ -90,7 +104,7 @@
/**
* tny_folder_get_stats:
- * @self: a #TnyFolder object
+ * @self: a #TnyFolder
*
* Get some statistics of the folder @self. The returned statistics object will
* not change after you got it. If you need an updated version, you need to call
@@ -101,7 +115,10 @@
* #TnyFolder that will get you the same counts in a less expensive way. With
* this method you get a combined statistic, however.
*
- * Return value: some statistics of the folder
+ * return (caller-owns): some statistics of the folder
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
TnyFolderStats*
tny_folder_get_stats (TnyFolder *self)
@@ -123,19 +140,24 @@
/**
* tny_folder_add_observer:
- * @self: a #TnyFolder instance
- * @observer: a #TnyFolderObserver instance
+ * @self: a #TnyFolder
+ * @observer: a #TnyFolderObserver
*
- * Add @observer to the list of interested observers for events that could happen
- * caused by for example a tny_folder_poke_status and other spontaneous changes
- * (like Push E-mail events).
+ * Add @observer to the list of event observers. Among the events that could
+ * happen are caused by for example a tny_folder_poke_status() and spontaneous
+ * change notifications like Push E-mail events.
*
- * After this, @observer will start receiving notification of changes about @self.
+ * After this, @observer will start receiving notification of changes about
+ * @self.
*
- * A weak reference is added to @observer. When @observer finalizes will @self
+ * A weak reference is added to @observer. When @observer finalises will @self
* automatically update itself by unregistering @observer. It's recommended to
- * use tny_folder_remove_observer yourself to unregister @observer as observer for
- * @self, though.
+ * use tny_folder_remove_observer yourself to unregister @observer as observer
+ * for @self.
+ *
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
void
tny_folder_add_observer (TnyFolder *self, TnyFolderObserver *observer)
@@ -154,15 +176,20 @@
/**
* tny_folder_remove_observer:
- * @self: a #TnyFolder instance
- * @observer: a #TnyFolderObserver instance
+ * @self: a #TnyFolder
+ * @observer: a #TnyFolderObserver
*
- * Remove @observer from the list of interested observers for events that could
- * happen caused by for example a tny_folder_poke_status and other spontaneous
- * changes (like Push E-mail events).
+ * Remove @observer from the list of event observers of @self.
*
- * After this, @observer will no longer receive notification of changes about @self.
+ * After this, @observer will no longer receive notification of changes about
+ * @self.
*
+ * The weak reference added by tny_folder_add_observer() to @observer, is
+ * removed.
+ *
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
void
tny_folder_remove_observer (TnyFolder *self, TnyFolderObserver *observer)
@@ -181,14 +208,18 @@
/**
* tny_folder_poke_status:
- * @self: a TnyFolder object
+ * @self: a #TnyFolder
*
- * Poke for the status, this will invoke the event of sending a #TnyFolderChange
- * to the observers. The change will always at least contain the unread and total
- * folder count, also if the unread and total didn't change at all. This makes
- * it possible for a model or view that shows folders to get the initial folder
+ * Poke for the status, this will invoke an event to the event observers of
+ * @self. The change will always at least contain the unread and total folder
+ * count, also if the unread and total didn't change at all. This makes it
+ * possible for a model or view that shows folders to get the initial folder
* unread and total counts (the #TnyGtkFolderStoreListModel uses this method
* internally, for example).
+ *
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
void
tny_folder_poke_status (TnyFolder *self)
@@ -205,12 +236,15 @@
/**
* tny_folder_get_msg_receive_strategy:
- * @self: a TnyFolder object
+ * @self: a #TnyFolder
*
* Get the strategy for receiving a message. The return value of this method
* must be unreferenced after use.
*
- * Return value: the strategy for receiving a message
+ * returns (caller-owns): the strategy for receiving a message
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
TnyMsgReceiveStrategy*
tny_folder_get_msg_receive_strategy (TnyFolder *self)
@@ -233,18 +267,24 @@
/**
* tny_folder_set_msg_receive_strategy:
- * @self: a TnyFolder object
- * @st: a #TnyMsgReceiveStrategy object
+ * @self: a #TnyFolder
+ * @st: a #TnyMsgReceiveStrategy
*
- * Set the strategy for receiving a message
+ * Set the strategy for receiving a message. Some common strategies are:
*
- * The idea is that devices can have a specific such strategy. For example a
- * strategy that receives the message fully from the service or a strategy that
- * receives it partially from the service (only the body)
+ * - #TnyCamelPartialMsgReceiveStrategy for a strategy that tries to only
+ * receive the text parts of an E-mail.
+ * - #TnyCamelFullMsgReceiveStrategy (current default) for a strategy that
+ * requests the entire message
+ * - #TnyCamelBsMsgReceiveStrategy for a strategy that receives a BODYSTRUCTURE
+ * and then per MIME part that is needed, requests the needed MIME part
*
- * For more information take a look at tny_msg_receive_strategy_peform_get_msg
+ * For more information take a look at tny_msg_receive_strategy_peform_get_msg()
* of #TnyMsgReceiveStrategy.
*
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
void
tny_folder_set_msg_receive_strategy (TnyFolder *self, TnyMsgReceiveStrategy *st)
@@ -274,11 +314,11 @@
/**
* tny_folder_copy:
- * @self: a #TnyFolder object
- * @into: a #TnyFolderStore object
+ * @self: a #TnyFolder
+ * @into: a #TnyFolderStore
* @new_name: the new name in @into
* @del: whether or not to delete the original location
- * @err: a #GError object or NULL
+ * @err (null-ok): a #GError object or NULL
*
* Copies @self to @into giving the new folder the name @new_name. Returns the
* newly created folder in @into, which will carry the name @new_name. For some
@@ -286,34 +326,36 @@
*
* It will do both copying and in case of @del being TRUE, removing too,
* recursively. If you don't want it to be recursive, you should in stead create
- * the folder @new_name in @into manually using tny_folder_store_create_folder
- * and then use the tny_folder_transfer_msgs API.
+ * the folder @new_name in @into manually using tny_folder_store_create_folder()
+ * and then use the tny_folder_transfer_msgs() API.
*
- * This method will always result in create observer events being throw for each
- * subfolder of @self that is copied or moved to @new_name in creation order
- * (parents first, childs after that).
+ * This method will result in create events being thrown to the observers of
+ * each subfolder of @self that is copied or moved to @new_name in creation
+ * order (parents first, childs after that).
*
* In case of @del being TRUE it will on top of that and before those create
- * events also result in remove observer events being throw for each subfolder
- * of @self in deletion order (the exact reversed order: childs first, parents
- * after that)
+ * events also result in remove events being thrown to the observers of each
+ * subfolder of @self in deletion order (the exact reversed order: childs
+ * first, parents after that)
*
* Standard folder models like the #TnyGtkFolderStoreListModel know about this
* behavior and will act by updating themselves automatically.
*
* When you are moving @self to @into with @del set to TRUE (moving @self), you
- * MUST make sure that @self nor any of its sub folders are used anymore. For
- * example if you have gotten headers using tny_folder_get_headers, you MUST get
- * rid of those first. In case you used a default component like the
- * TnyGtkHeaderListModel or any other TnyList for storing the headers, you can
+ * must make sure that @self nor any of its sub folders are used anymore. For
+ * example if you have gotten headers using tny_folder_get_headers(), you must
+ * get rid of those first. In case you used a default component like the
+ * #TnyGtkHeaderListModel or any other #TnyList for storing the headers, you can
* easily get rid if your headers by setting the model of the GtkTreeView to
- * an empty one or unreferencing the list. You MUST NOT try to keep using it nor
- * any of its headers. These instances will be invalid and in a destroyed state.
+ * an empty one or unreferencing the list.
*
* If @new_name already exists in @into and @err is not NULL, then an error will
* be set in @err and no further action will be performed.
*
- * Return value: a new folder instance to whom was copied or NULL in case of failure
+ * returns (null-ok) (caller-owns): a new folder instance to whom was copied or NULL
+ * since: 1.0
+ * complexity: high
+ * audience: application-developer
**/
TnyFolder*
tny_folder_copy (TnyFolder *self, TnyFolderStore *into, const gchar *new_name, gboolean del, GError **err)
@@ -348,59 +390,16 @@
/**
* tny_folder_copy_async:
- * @self: a #TnyFolder object
- * @into: a #TnyFolderStore object
+ * @self: a #TnyFolder
+ * @into: a #TnyFolderStore
* @new_name: the new name in @into
* @del: whether or not to delete the original location
- * @callback: callback that happens when the operation finished
- * @status_callback: cllback that'll happen whenever there's status
- * @user_data: user data
+ * @callback (null-ok): a #TnyCopyFolderCallback or NULL
+ * @status_callback (null-ok): a #TnyStatusCallback or NULL
+ * @user_data (null-ok): user data that will be passed to the callbacks
*
- * Copies @self to @into giving the new folder the name @new_name. Returns the
- * newly created folder in @into, which will carry the name @new_name. For some
- * remote services this functionality is implemented as a rename operation.
+ * See tny_folder_copy(). This is the asynchronous version of the same function.
*
- * It will do both copying and in case of @del being TRUE, removing too,
- * recursively. If you don't want it to be recursive, you should in stead create
- * the folder @new_name in @into manually using tny_folder_store_create_folder
- * and then use the tny_folder_transfer_msgs API.
- *
- * This method will always result in create observer events being throw for each
- * subfolder of @self that is copied or moved to @new_name in creation order
- * (parents first, childs after that).
- *
- * In case of @del being TRUE it will on top of that and before those create
- * events also result in remove observer events being throw for each subfolder
- * of @self in deletion order (the exact reversed order: childs first, parents
- * after that)
- *
- * Standard folder models like the #TnyGtkFolderStoreListModel know about this
- * behavior and will act by updating themselves automatically.
- *
- * When you are moving @self to @into with @del set to TRUE (moving @self), you
- * MUST make sure that @self nor any of its sub folders are used anymore. For
- * example if you have gotten headers using tny_folder_get_headers, you MUST get
- * rid of those first. In case you used a default component like the
- * TnyGtkHeaderListModel or any other TnyList for storing the headers, you can
- * easily get rid if your headers by setting the model of the GtkTreeView to
- * an empty one or unreferencing the list. You MUST NOT try to keep using it nor
- * any of its headers. These instances will be invalid and in a destroyed state.
- *
- * If @new_name already exists in @into and @err is not NULL, then an error will
- * be set in @err and no further action will be performed.
- *
- * If you want to use this method, it's advised to let your application
- * use the #GMainLoop. All Gtk+ applications have this once gtk_main () is
- * called.
- *
- * When using a #GMainLoop this method will callback using g_idle_add_full.
- * Without a #GMainLoop, which the libtinymail-camel implementation detects
- * using (g_main_depth > 0), the callbacks will happen in a worker thread at an
- * unknown moment in time (check your locking in this case).
- *
- * When using Gtk+, the callback doesn't need the gdk_threads_enter and
- * gdk_threads_leave guards (because it happens in the #GMainLoop).
- *
* Example:
* <informalexample><programlisting>
* static void
@@ -411,8 +410,7 @@
* static void
* folder_copy_cb (TnyFolder *folder, TnyFolderStore *into, const gchar *new_name, gboolean cancelled, GError **err, gpointer user_data)
* {
- * if (!cancelled)
- * {
+ * if (!cancelled) {
* TnyList *headers = tny_simple_list_new ();
* TnyIterator *iter;
* g_print ("done\nHeaders copied into %s are:",
@@ -423,10 +421,10 @@
* {
* TnyHeader *header = tny_iterator_current (iter);
* g_print ("\t%s\n", tny_header_get_subject (header));
- * g_object_unref (G_OBJECT (header));
+ * g_object_unref (header);
* tny_iterator_next (iter);
* }
- * g_object_unref (G_OBJECT (headers));
+ * g_object_unref (headers);
* }
* }
* TnyFolder *folder = ...
@@ -437,6 +435,10 @@
* folder_copy_cb,
* status_update_cb, NULL);
* </programlisting></informalexample>
+ *
+ * since: 1.0
+ * complexity: high
+ * audience: application-developer
**/
void
tny_folder_copy_async (TnyFolder *self, TnyFolderStore *into, const gchar *new_name, gboolean del, TnyCopyFolderCallback callback, TnyStatusCallback status_callback, gpointer user_data)
@@ -452,19 +454,23 @@
TNY_FOLDER_GET_IFACE (self)->copy_async_func (self, into, new_name, del, callback, status_callback, user_data);
+#ifdef DBC /* ensure */
+#endif
+
+ return;
}
/**
* tny_folder_get_msg_remove_strategy:
- * @self: a TnyFolder object
+ * @self: a #TnyFolder
*
* Get the strategy for removing a message. The return value of this method
* must be unreferenced after use.
*
- * Implementors: This method must return the strategy for removing a message.
- * being the implementer, you must add a reference before returning the instance.
- *
- * Return value: the strategy for removing a message
+ * returns (caller-owns): the strategy for removing a message
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
TnyMsgRemoveStrategy*
tny_folder_get_msg_remove_strategy (TnyFolder *self)
@@ -487,22 +493,17 @@
/**
* tny_folder_set_msg_remove_strategy:
- * @self: a TnyFolder object
- * @st: a #TnyMsgRemoveStrategy object
+ * @self: a #TnyFolder
+ * @st: a #TnyMsgRemoveStrategy
*
* Set the strategy for removing a message
*
- * Implementors: This method must set (store) the strategy for removing a
- * message.
- *
- * The idea is that devices can have a specific such strategy. For example a
- * strategy that removes it immediately from both local cache and a service
- * or a strategy that does nothing but flag the message for removal upon next
- * expunge or a strategy that does nothing.
- *
- * For more information take a look at tny_msg_remove_strategy_peform_remove
+ * For more information take a look at tny_msg_remove_strategy_peform_remove()
* of #TnyMsgRemoveStrategy.
- *
+ *
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
void
tny_folder_set_msg_remove_strategy (TnyFolder *self, TnyMsgRemoveStrategy *st)
@@ -530,9 +531,9 @@
/**
* tny_folder_sync:
- * @self: a #TnyFolder object
- * @expunge: whether or not to also expunge deleted messages
- * @err: a #GError object or NULL
+ * @self: a #TnyFolder
+ * @expunge: also expunge deleted messages
+ * @err (null-ok): a #GError or NULL
*
* Persist changes made to a folder to its backing store, expunging deleted
* messages (the ones marked with TNY_HEADER_FLAG_DELETED) as well if @expunge
@@ -544,10 +545,14 @@
* TnyFolder *folder = tny_header_get_folder (header);
* tny_folder_remove_msg (folder, header, NULL);
* tny_list_remove (TNY_LIST (mymodel), G_OBJECT (header));
- * g_object_unref (G_OBJECT (header));
+ * g_object_unref (header);
* tny_folder_sync (folder, TRUE, NULL);
- * g_object_unref (G_OBJECT (folder));
+ * g_object_unref (folder);
* </programlisting></informalexample>
+ *
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
void
tny_folder_sync (TnyFolder *self, gboolean expunge, GError **err)
@@ -564,19 +569,23 @@
/**
* tny_folder_sync_async:
- * @self: a #TnyFolder object
- * @expunge: whether or not to also expunge deleted messages
- * @callback: a #TnySyncFolderCallback
- * @status_callback: a #TnyStatusCallback
- * @user_data: user data that will be passed to the callbacks
+ * @self: a #TnyFolder
+ * @expunge: also expunge deleted messages
+ * @callback (null-ok): a #TnySyncFolderCallback or NULL
+ * @status_callback (null-ok): a #TnyStatusCallback or NULL
+ * @user_data (null-ok): user data that will be passed to the callbacks
*
* The authors of Tinymail know that sync async sounds paradoxical. Though if
* you think about it, it makes perfect sense: you synchronize the content in
- * an asynchronous way. Nothing paradoxial about it, right?
+ * an asynchronous way. Nothing paradoxical about it, right?
*
* Persist changes made to a folder to its backing store, expunging deleted
* messages (the ones marked with TNY_HEADER_FLAG_DELETED) as well if @expunge
* is TRUE.
+ *
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
void
tny_folder_sync_async (TnyFolder *self, gboolean expunge, TnyFolderCallback callback, TnyStatusCallback status_callback, gpointer user_data)
@@ -593,19 +602,22 @@
/**
* tny_folder_add_msg_async:
- * @self: a #TnyFolder object
- * @msg: a #TnyMsg object
- * @callback: a callback that'll happen when adding is finished
- * @status_callback: a status callback
- * @user_data: user data for the status callback and callback
+ * @self: a #TnyFolder
+ * @msg: a #TnyMsg
+ * @callback (null-ok): a #TnyFolderCallback or NULL
+ * @status_callback (null-ok): a #TnyStatusCallback or NULL
+ * @user_data (null-ok): user data that will be passed to the callbacks
*
- * Add a message to a folder. It's recommended to destroy @msg afterwards because
+ * Add a message to a @self. It's recommended to destroy @msg afterwards because
* after receiving the same message from the folder again, the instance wont be
- * the same anymore and a property like the tny_msg_get_id might have changed
- * and assigned too.
+ * the same and a property like the tny_msg_get_id() will have changed.
*
- * Folder observers of @self will get a header-added trigger caused by this
+ * Folder observers of @self will get a header-added event caused by this
* action.
+ *
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
void
tny_folder_add_msg_async (TnyFolder *self, TnyMsg *msg, TnyFolderCallback callback, TnyStatusCallback status_callback, gpointer user_data)
@@ -623,17 +635,20 @@
/**
* tny_folder_add_msg:
- * @self: a #TnyFolder object
- * @msg: a #TnyMsg object
- * @err: a #GError object or NULL
+ * @self: a #TnyFolder
+ * @msg: a #TnyMsg
+ * @err (null-ok): a #GError or NULL
*
- * Add a message to a folder. It's recommended to destroy @msg afterwards because
+ * Add a message to a @self. It's recommended to destroy @msg afterwards because
* after receiving the same message from the folder again, the instance wont be
- * the same anymore and a property like the tny_msg_get_id might have changed
- * and assigned too.
+ * the same and a property like the tny_msg_get_id() will have changed.
*
- * Folder observers of @self will get a header-added trigger caused by this
+ * Folder observers of @self will get a header-added event caused by this
* action.
+ *
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
void
tny_folder_add_msg (TnyFolder *self, TnyMsg *msg, GError **err)
@@ -650,17 +665,16 @@
/**
* tny_folder_remove_msg:
- * @self: a TnyFolder object
- * @header: the header of the message to remove
- * @err: a #GError object or NULL
+ * @self: a #TnyFolder
+ * @header: a #TnyHeader of the message to remove
+ * @err: a #GError or NULL
*
- * Remove a message from a folder. It will use a #TnyMsgRemoveStrategy to
- * perform the removal itself. For more details, check out the documentation
- * of the #TnyMsgRemoveStrategy type and the implementation that you activated
- * using tny_folder_set_msg_remove_strategy. The default implementation for
- * libtinymail-camel is the #TnyCamelMsgRemoveStrategy.
+ * Remove a message from a folder. It will use the #TnyMsgRemoveStrategy of
+ * @self to perform the removal itself. For more details, check out the
+ * documentation of the used #TnyMsgRemoveStrategy type. The default
+ * implementation for libtinymail-camel is the #TnyCamelMsgRemoveStrategy.
*
- * Folder observers of @self will get a header-removed trigger caused by this
+ * Folder observers of @self will get a header-removed event caused by this
* action.
*
* Example:
@@ -668,8 +682,7 @@
* static void
* on_header_view_key_press_event (GtkTreeView *header_view, GdkEventKey *event, gpointer user_data)
* {
- * if (event->keyval == GDK_Delete)
- * {
+ * if (event->keyval == GDK_Delete) {
* GtkTreeSelection *selection;
* GtkTreeModel *model;
* GtkTreeIter iter;
@@ -683,13 +696,16 @@
* TnyFolder *folder = tny_header_get_folder (header);
* tny_folder_remove_msg (folder, header, NULL);
* tny_list_remove (TNY_LIST (model), G_OBJECT (header));
- * g_object_unref (G_OBJECT (folder));
- * g_object_unref (G_OBJECT (header));
+ * g_object_unref (folder);
+ * g_object_unref (header);
* }
* }
* }
* </programlisting></informalexample>
*
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
void
tny_folder_remove_msg (TnyFolder *self, TnyHeader *header, GError **err)
@@ -707,20 +723,22 @@
/**
* tny_folder_remove_msgs:
- * @self: a TnyFolder object
- * @headers: the headers of the messages to remove
- * @err: a #GError object or NULL
+ * @self: a #TnyFolder
+ * @headers: a #TnyList with #TnyHeader items of the messages to remove
+ * @err: a #GError or NULL
*
- * Remove messages from a folder. It will use a #TnyMsgRemoveStrategy to
- * perform the removal itself. For more details, check out the documentation
- * of the #TnyMsgRemoveStrategy type and the implementation that you activated
- * using tny_folder_set_msg_remove_strategy. The default implementation for
- * libtinymail-camel is the #TnyCamelMsgRemoveStrategy.
+ * Remove messages from a folder. It will use the #TnyMsgRemoveStrategy of
+ * @self to perform the removal itself. For more details, check out the
+ * documentation of the used #TnyMsgRemoveStrategy type. The default
+ * implementation for libtinymail-camel is the #TnyCamelMsgRemoveStrategy.
*
- * Folder observers of @self will get only one header-removed trigger caused by this
- * action.
+ * Folder observers of @self will get only one header-removed trigger caused
+ * by this action (with all the removed headers in the #TnyFolderChange).
*
- */
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
+ **/
void
tny_folder_remove_msgs (TnyFolder *self, TnyList *headers, GError **err)
{
@@ -737,30 +755,23 @@
/**
* tny_folder_refresh_async:
- * @self: a TnyFolder object
- * @callback: The callback handler. This is called last.
- * @status_callback: A callback for status notifications. This is never called after @callback.
- * @user_data: user data for the callback
+ * @self: a #TnyFolder
+ * @callback (null-ok): a #TnyFolderCallback or NULL
+ * @status_callback (null-ok): a #TnyStatusCallback or NULL
+ * @user_data (null-ok): user data that will be passed to the callbacks
*
- * Refresh @self and call back when finished. This gets the summary information
- * from the E-Mail service, writes it to the the on-disk cache and/or updates
- * it.
+ * Refresh @self and callback when finished. This gets the summary information
+ * from the E-Mail service, writes it to the the on-disk cache and/or updates it.
*
- * After this method, tny_folder_get_all_count and
- * tny_folder_get_unread_count are guaranteed to be correct.
+ * After this method, when @callback takes place, tny_folder_get_all_count()
+ * and tny_folder_get_unread_count() are guaranteed to be correct. The API
+ * tny_folder_get_headers() is guaranteed to put an accurate list of headers
+ * in the provided #TnyList.
*
- * If you want to use this method, it's advised to let your application
- * use the #GMainLoop. All Gtk+ applications have this once gtk_main () is
- * called.
- *
- * When using a #GMainLoop this method will callback using g_idle_add_full.
- * Without a #GMainLoop, which the libtinymail-camel implementation detects
- * using (g_main_depth > 0), the callbacks will happen in a worker thread at an
- * unknown moment in time (check your locking in this case).
+ * While the refresh takes place, it's possible that event observers of @self
+ * will get notified of new header additions. #TnyFolderMonitor copes with those
+ * by publishing them to #TnyList instances, like a #TnyGtkHeaderListModel.
*
- * When using Gtk+, the callback doesn't need the gdk_threads_enter and
- * gdk_threads_leave guards (because it happens in the #GMainLoop).
- *
* Example:
* <informalexample><programlisting>
* static void
@@ -783,10 +794,10 @@
* {
* TnyHeader *header = tny_iterator_current (iter);
* g_print ("\t%s\n", tny_header_get_subject (header));
- * g_object_unref (G_OBJECT (header));
+ * g_object_unref (header);
* tny_iterator_next (iter);
* }
- * g_object_unref (G_OBJECT (headers));
+ * g_object_unref (headers);
* }
* }
* TnyFolder *folder = ...
@@ -795,6 +806,10 @@
* folder_refresh_cb,
* status_update_cb, NULL);
* </programlisting></informalexample>
+ *
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
void
tny_folder_refresh_async (TnyFolder *self, TnyFolderCallback callback, TnyStatusCallback status_callback, gpointer user_data)
@@ -813,17 +828,26 @@
/**
* tny_folder_refresh:
- * @self: a TnyFolder object
- * @err: a #GError object or NULL
+ * @self: a #TnyFolder
+ * @err: a #GError or NULL
*
- * Refresh the folder. This gets the summary information from the E-Mail
- * service, writes it to the the on-disk cache and/or updates it.
+ * Refresh @self. This gets the summary information from the E-Mail service,
+ * writes it to the the on-disk cache and/or updates it.
*
- * After this method, tny_folder_get_all_count and
- * tny_folder_get_unread_count are guaranteed to be correct.
+ * After this method tny_folder_get_all_count() and tny_folder_get_unread_count()
+ * are guaranteed to be correct. The API tny_folder_get_headers() is guaranteed to
+ * put an accurate list of headers in the provided #TnyList.
*
- * Also read about tny_folder_get_headers.
+ * While the refresh takes place, it's possible that event observers of @self
+ * will get notified of new header additions. #TnyFolderMonitor copes with those
+ * by publishing them to #TnyList instances, like a #TnyGtkHeaderListModel.
*
+ * This function can take a very long time. You are advised to consider using
+ * tny_folder_refresh_async() in stead.
+ *
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
void
tny_folder_refresh (TnyFolder *self, GError **err)
@@ -840,11 +864,14 @@
/**
* tny_folder_is_subscribed:
- * @self: a TnyFolder object
+ * @self: a #TnyFolder
*
- * Get the subscribtion status of this folder.
+ * Get the subscription status of @self.
*
- * Return value: subscribe status
+ * returns: subscription state
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
gboolean
tny_folder_is_subscribed (TnyFolder *self)
@@ -859,14 +886,16 @@
/**
* tny_folder_get_unread_count:
- * @self: a TnyFolder object
+ * @self: a #TnyFolder
*
* Get the amount of unread messages in this folder. The value is only
- * garuanteed to be correct after tny_folder_refresh or after the callback of
- * a tny_folder_refresh_async happened.
+ * guaranteed to be correct after tny_folder_refresh() or during the
+ * callback of a tny_folder_refresh_async().
*
- * Return value: amount of unread messages
- *
+ * returns: amount of unread messages
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
guint
tny_folder_get_unread_count (TnyFolder *self)
@@ -882,13 +911,15 @@
/**
* tny_folder_get_local_size:
- * @self: a TnyFolder object
+ * @self: a #TnyFolder
*
* Get the local size of this folder in bytes. Local size means the amount of
- * disk space that this folder consumes.
+ * disk space that this folder consumes locally in the caches.
*
- * Return value: get the local size of this folder
- *
+ * returns: get the local size of this folder
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
guint
tny_folder_get_local_size (TnyFolder *self)
@@ -903,14 +934,16 @@
/**
* tny_folder_get_all_count:
- * @self: a TnyFolder object
+ * @self: a #TnyFolder
*
- * Get the amount of messages in this folder. The value is only garuanteed to be
- * correct after tny_folder_refresh or after the callback of a
- * tny_folder_refresh_async happened.
+ * Get the amount of messages in this folder. The value is only guaranteed to
+ * be correct after tny_folder_refresh() or during the callback of a
+ * tny_folder_refresh_async().
*
- * Return value: amount of messages
- *
+ * returns: amount of messages
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
guint
tny_folder_get_all_count (TnyFolder *self)
@@ -925,13 +958,15 @@
/**
* tny_folder_get_account:
- * @self: a TnyFolder object
+ * @self: a #TnyFolder
*
- * Get a the parent account of this folder or NULL. If not NULL, you must
- * unreference the return value after use.
+ * Get a the account of this folder or NULL. If not NULL, you must unreference
+ * the return value after use.
*
- * Return value: the account of this folder or NULL
- *
+ * returns (null-ok) (caller-owns): the account of this folder or NULL
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
TnyAccount*
tny_folder_get_account (TnyFolder *self)
@@ -956,18 +991,23 @@
/**
* tny_folder_transfer_msgs:
- * @self: the TnyFolder where the headers are stored
- * @header_list: a list of TnyHeader objects
- * @folder_dst: the TnyFolder where the msgs will be transfered
- * @delete_originals: if TRUE then move msgs, else copy them
- * @err: a #GError object or NULL
+ * @self: a #TnyFolder
+ * @header_list: a #TnyList of #TnyHeader instances in @self to move
+ * @folder_dst: a destination #TnyFolder
+ * @delete_originals: TRUE moves msgs, FALSE copies
+ * @err: a #GError or NULL
*
* Transfers messages of which the headers are in @header_list from @self to
* @folder_dst. They could be moved or just copied depending on the value of
* the @delete_originals argument.
*
- * You must not use header instances that you got from tny_msg_get_header with
- * this API. You must only use instances that you got from tny_folder_get_headers!
+ * You must not use header instances that you got from tny_msg_get_header()
+ * with this API. You must only use instances that you got from
+ * tny_folder_get_headers().
+ *
+ * since: 1.0
+ * complexity: high
+ * audience: application-developer
**/
void
tny_folder_transfer_msgs (TnyFolder *self, TnyList *headers, TnyFolder *folder_dst, gboolean delete_originals, GError **err)
@@ -987,32 +1027,25 @@
/**
* tny_folder_transfer_msgs_async:
- * @self: the TnyFolder where the headers are stored
- * @header_list: a list of TnyHeader objects
- * @folder_dst: the TnyFolder where the msgs will be transfered
- * @delete_originals: if TRUE then move msgs, else copy them
- * @callback: The callback handler
- * @status_callback: the status callback handler
- * @user_data: user data for the callback
+ * @self: a #TnyFolder
+ * @header_list: a #TnyList of #TnyHeader instances in @self to move
+ * @folder_dst: a destination #TnyFolder
+ * @delete_originals: TRUE moves msgs, FALSE copies
+ * @callback (null-ok): a #TnyTransferMsgsCallback or NULL
+ * @status_callback (null-ok): a #TnyStatusCallback or NULL
+ * @user_data (null-ok): user data that will be passed to the callbacks
*
* Transfers messages of which the headers are in @header_list from @self to
* @folder_dst. They could be moved or just copied depending on the value of
- * the @delete_originals argument
+ * the @delete_originals argument.
*
- * If you want to use this functionality, it's advised to let your application
- * use the #GMainLoop. All Gtk+ applications have this once gtk_main () is
- * called.
- *
- * When using a #GMainLoop this method will callback using g_idle_add_full.
- * Without a #GMainLoop, which the libtinymail-camel implementation detects
- * using (g_main_depth > 0), the callbacks will happen in a worker thread at an
- * unknown moment in time (check your locking).
+ * You must not use header instances that you got from tny_msg_get_header()
+ * with this API. You must only use instances that you got from
+ * tny_folder_get_headers().
*
- * When using Gtk+, the callback doesn't need the gdk_threads_enter and
- * gdk_threads_leave guards (because it happens in the #GMainLoop).
- *
- * You must not use header instances that you got from tny_msg_get_header with
- * this API. You must only use instances that you got from tny_folder_get_headers!
+ * since: 1.0
+ * complexity: high
+ * audience: application-developer
**/
void
tny_folder_transfer_msgs_async (TnyFolder *self, TnyList *header_list, TnyFolder *folder_dst, gboolean delete_originals, TnyTransferMsgsCallback callback, TnyStatusCallback status_callback, gpointer user_data)
@@ -1033,9 +1066,9 @@
/**
* tny_folder_get_msg:
- * @self: a #TnyFolder object
- * @header: the header of the message to get
- * @err: a #GError object or NULL
+ * @self: a #TnyFolder
+ * @header: a #TnyHeader the message to get
+ * @err: a #GError or NULL
*
* Get a message in @self identified by @header. If not NULL, you must
* unreference the return value after use.
@@ -1051,16 +1084,17 @@
* </programlisting></informalexample>
*
* Note that once you received the message this way, the entire message instance
- * is detached from any folder. This means that if you get the header using the
- * tny_msg_get_header API, that this header can't be used with folder API like
- * tny_folder_transfer_msgs and tny_folder_transfer_msgs_async. You can only
- * use header instances that you got with tny_folder_get_headers for these and
- * other such methods. The message's instance nor its header also wont receive
- * updates from the observable folder (like what a TnyFolderObserver would do,
- * for example in case a message got removed from the remote store, like the
- * folder on the IMAP server).
+ * is detached from @self. This means that if you get a new header using the
+ * tny_msg_get_header() API, that this header can't be used with folder API like
+ * tny_folder_transfer_msgs() and tny_folder_transfer_msgs_async(). You can only
+ * use header instances that you got with tny_folder_get_headers() for this and
+ * other #TnyFolder methods. The message's instance nor its header will receive
+ * updates from the observable folder.
*
- * Return value: The message instance or NULL on failure
+ * returns (null-ok) (caller-owns): The message instance or NULL
+ * since: 1.0
+ * complexity: high
+ * audience: application-developer
**/
TnyMsg*
tny_folder_get_msg (TnyFolder *self, TnyHeader *header, GError **err)
@@ -1088,13 +1122,13 @@
/**
* tny_folder_find_msg:
- * @self: a #TnyFolder object
+ * @self: a #TnyFolder
* @url_string: the url string
- * @err: a #GError object or NULL
+ * @err: a #GError or NULL
*
- * Get a message in @self identified by @url_string. If not NULL, you must
- * unreference the return value after use.
- * See tny_folder_get_url_string() for details of the @url-string syntax.
+ * Get the message in @self identified by @url_string. If not NULL, you must
+ * unreference the return value after use. See tny_folder_get_url_string() for
+ * details of the @url-string syntax.
*
* Example:
* <informalexample><programlisting>
@@ -1102,11 +1136,13 @@
* TnyFolder *folder = ...
* TnyMsg *message = tny_folder_find_msg (folder, "imap://account/INBOX/100", NULL);
* tny_msg_view_set_msg (message_view, message);
- * g_object_unref (G_OBJECT (message));
+ * g_object_unref (message);
* </programlisting></informalexample>
*
- * Return value: The message instance or NULL on failure
- *
+ * returns (null-ok) (caller-owns): The message instance or NULL
+ * since: 1.0
+ * complexity: high
+ * audience: application-developer
**/
TnyMsg*
tny_folder_find_msg (TnyFolder *self, const gchar *url_string, GError **err)
@@ -1134,26 +1170,14 @@
/**
* tny_folder_get_msg_async:
- * @self: a #TnyFolder object
- * @header: a #TnyHeader object
- * @callback: The callback handler
- * @status_callback: the status callback handler
- * @user_data: user data for the callback
+ * @self: a #TnyFolder
+ * @header: a #TnyHeader of the message to get
+ * @callback (null-ok): a #TnyGetMsgCallback or NULL
+ * @status_callback (null-ok): a #TnyStatusCallback or NULL
+ * @user_data (null-ok): user data that will be passed to the callbacks
*
- * Get a message in @self identified by @header.
+ * Get a message in @self identified by @header asynchronously.
*
- * If you want to use this functionality, it's advised to let your application
- * use the #GMainLoop. All Gtk+ applications have this once gtk_main () is
- * called.
- *
- * When using a #GMainLoop this method will callback using g_idle_add_full.
- * Without a #GMainLoop, which the libtinymail-camel implementation detects
- * using (g_main_depth > 0), the callbacks will happen in a worker thread at an
- * unknown moment in time (check your locking).
- *
- * When using Gtk+, the callback doesn't need the gdk_threads_enter and
- * gdk_threads_leave guards (because it happens in the #GMainLoop).
- *
* Example:
* <informalexample><programlisting>
* static void
@@ -1162,16 +1186,21 @@
* printf (".");
* }
* static void
- * folder_get_msg_cb (TnyFolder *folder, TnyMsg *msg, GError **err, gpointer user_data)
+ * folder_get_msg_cb (TnyFolder *folder, gboolean cancelled, TnyMsg *msg, GError **err, gpointer user_data)
* {
* TnyMsgView *message_view = user_data;
- * tny_msg_view_set_msg (message_view, message);
+ * if (!err && msg && !cancelled)
+ * tny_msg_view_set_msg (message_view, msg);
* }
* TnyMsgView *message_view = tny_platform_factory_new_msg_view (platfact);
* TnyFolder *folder = ...; TnyHeader *header = ...;
* tny_folder_get_msg_async (folder, header,
* folder_get_msg_cb, status_cb, message_view);
* </programlisting></informalexample>
+ *
+ * since: 1.0
+ * complexity: high
+ * audience: application-developer
**/
void
tny_folder_get_msg_async (TnyFolder *self, TnyHeader *header, TnyGetMsgCallback callback, TnyStatusCallback status_callback, gpointer user_data)
@@ -1190,13 +1219,13 @@
/**
* tny_folder_get_headers:
- * @self: a TnyFolder object
- * @headers: A #TnyList instance where the headers will be put
- * @refresh: whether or not to synchronize with the service first
- * @err: a #GError object or NULL
+ * @self: a #TnyFolder
+ * @headers: A #TnyList where the headers will be prepended to
+ * @refresh: synchronize with the service first
+ * @err: a #GError or NULL
*
* Get the list of message header instances that are in @self. Also read
- * about tny_folder_refresh.
+ * about tny_folder_refresh() and tny_folder_refresh_async().
*
* API warning: it's possible that between the @refresh and @err, a pointer to
* a query object will be placed. This will introduce both an API and ABI
@@ -1213,12 +1242,16 @@
* {
* TnyHeader *header = tny_iterator_get_current (iter);
* g_print ("%s\n", tny_header_get_subject (header));
- * g_object_unref (G_OBJECT (header));
+ * g_object_unref (header);
* tny_iterator_next (iter);
* }
- * g_object_unref (G_OBJECT (iter));
- * g_object_unref (G_OBJECT (headers));
+ * g_object_unref (iter);
+ * g_object_unref (headers);
* </programlisting></informalexample>
+ *
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
void
tny_folder_get_headers (TnyFolder *self, TnyList *headers, gboolean refresh, GError **err)
@@ -1237,19 +1270,23 @@
/**
* tny_folder_get_headers_async:
- * @self: a TnyFolder object
- * @headers: A #TnyList instance where the headers will be put
- * @refresh: whether or not to synchronize with the service first
- * @callback: the callback that happens when the operation finished
- * @status_callback: status callback
- * @user_data: user data
+ * @self: a TnyFolder
+ * @headers: A #TnyList where the headers will be prepended to
+ * @refresh: synchronize with the service first
+ * @callback (null-ok): a #TnyGetHeadersCallback or NULL
+ * @status_callback (null-ok): a #TnyStatusCallback or NULL
+ * @user_data (null-ok): user data that will be passed to the callbacks
*
* Get the list of message header instances that are in @self. Also read
- * about tny_folder_refresh.
+ * about tny_folder_refresh() and tny_folder_refresh_async().
*
* API warning: it's possible that between the @refresh and @callback, a pointer
* to a query object will be placed. This will introduce both an API and ABI
* breakage.
+ *
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
void
tny_folder_get_headers_async (TnyFolder *self, TnyList *headers, gboolean refresh, TnyGetHeadersCallback callback, TnyStatusCallback status_callback, gpointer user_data)
@@ -1268,18 +1305,20 @@
/**
* tny_folder_get_id:
- * @self: a TnyFolder object
+ * @self: a TnyFolder
*
- * Get an unique id of @self (unique per account). The ID will usually be a "/"
- * separated string like (but not guaranteed) "INBOX/parent-folder/folder"
- * depending on the service type (the example is for IMAP using the
- * libtinymail-camel implementation).
+ * Get an unique id of @self (unique per account). The id will usually be a
+ * string separated with slashes or backslashes like (but not guaranteed)
+ * "INBOX/parent-folder/folder" depending on the service type (this example is
+ * for IMAP using the libtinymail-camel implementation).
*
- * The ID is guaranteed to be unique per account. You should not free the result
+ * The ID is guaranteed to be unique per account. You must not free the result
* of this method.
*
- * Return value: A unique id
- *
+ * returns: unique id
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
const gchar*
tny_folder_get_id (TnyFolder *self)
@@ -1302,13 +1341,15 @@
/**
* tny_folder_get_name:
- * @self: a TnyFolder object
+ * @self: a #TnyFolder
*
- * Get the displayable name @of self. You should not free the result of
+ * Get the displayable name of @self. You should not free the result of
* this method.
*
- * Return value: The folder name
- *
+ * returns: folder name
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
const gchar*
tny_folder_get_name (TnyFolder *self)
@@ -1333,16 +1374,18 @@
/**
* tny_folder_get_folder_type:
- * @self: a TnyFolder object
+ * @self: a #TnyFolder
*
- * Get the type of @self (Inbox, Outbox etc.)
- * Most implementations decide the type by comparing the name of the folder
- * with some hardcoded values.
- * Some implementations (such as camel) might not provide precise information
- * before a connection has been made. For instance, the return value might
- * be TNY_FOLDER_TYPE_NORMAL rather than TNY_FOLDER_TYPE_SENT.
+ * Get the type of @self (Inbox, Outbox etc.). Most implementations decide the
+ * type by comparing the name of the folder with some hardcoded values. Some
+ * implementations (such as camel) might not provide precise information before
+ * a connection has been made. For instance, the return value might be
+ * TNY_FOLDER_TYPE_NORMAL rather than TNY_FOLDER_TYPE_SENT.
*
- * Return value: The folder type as a #TnyFolderType enum
+ * returns: folder type
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
TnyFolderType
tny_folder_get_folder_type (TnyFolder *self)
@@ -1358,15 +1401,16 @@
/**
* tny_folder_get_folder_store:
- * @self: a TnyFolder object
+ * @self: a #TnyFolder
*
- * Get a the parent store of this folder. You must unreference the
- * return value after use. Note that not every folder strictly has to
- * be inside a folder store.
+ * Get a the parent #TnyFolderStore of this folder. You must unreference the
+ * return value after use if not NULL. Note that not every folder strictly has
+ * to be inside a folder store. This API will in that case return NULL.
*
- * Return value: the folder store of this folder, or NULL if the
- * folder is not inside a folder store
- *
+ * returns (null-ok) (caller-owns): the folder store of this folder or NULL
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
TnyFolderStore*
tny_folder_get_folder_store (TnyFolder *self)
@@ -1432,7 +1476,7 @@
*
* GType system helper function
*
- * Return value: a GType
+ * returns: a #GType
**/
GType
tny_folder_type_get_type (void)
@@ -1468,7 +1512,7 @@
*
* GType system helper function
*
- * Return value: a GType
+ * returns: a #GType
**/
GType
tny_folder_caps_get_type (void)
@@ -1491,7 +1535,7 @@
*
* GType system helper function
*
- * Return value: a GType
+ * returns: a #GType
**/
GType
tny_folder_signal_get_type (void)
Index: libtinymail/tny-list.c
===================================================================
--- libtinymail/tny-list.c (revision 3137)
+++ libtinymail/tny-list.c (working copy)
@@ -17,17 +17,29 @@
* Boston, MA 02110-1301, USA.
*/
+/**
+ * TnyList:
+ *
+ * A list of things
+ *
+ * free-function: g_object_unref
+ * type-parameter: G
+ */
+
#include <config.h>
#include <tny-list.h>
/**
* tny_list_get_length:
- * @self: A #TnyList instance
+ * @self: A #TnyList
*
* Get the amount of items in @self.
*
- * Return value: the length of the list
+ * returns: the length of the list
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer, type-implementer
**/
guint
tny_list_get_length (TnyList *self)
@@ -42,38 +54,28 @@
/**
* tny_list_prepend:
- * @self: A #TnyList instance
- * @item: the item to prepend
+ * @self: A #TnyList
+ * @item (type-parameter G): the item to prepend
*
* Prepends an item to a list. You can only prepend items that inherit from the
- * GObject base item. That's because the tinymail list infrastructure does
- * reference counting. It effectively means that indeed you can't use non
- * GObject types in a tinymail list. But there's not a single situation where
- * you must do that. If you must store a non GObject in a list, you shouldn't
- * use the tinymail infrastructure for this. Consider using a doubly linked list
- * or a pointer array or any other list-type available on your development
- * platform.
+ * GObject base item. That's because Tinymail's list infrastructure does
+ * reference counting. Consider using a doubly linked list, a pointer array or
+ * any other list-type available on your development platform for non-GObject
+ * lists.
*
- * However, tinymail lists can cope with any valid GObject. Not just the
- * GObjects implemented by the tinymail framework.
+ * The @item you add will get a reference added by @self, with @self claiming
+ * ownership of @item. When @self is finalised, that reference is taken from
+ * @item.
*
- * All reference handling in tinymail is reference neutral. Also the lists. This
- * means that if your plan is to reparent the item to the list, that you should
- * take care of that by, after prepending or appending it, unreferencing it to
- * get rid of its initial reference. If you don't want to reparent, but you do
- * want to destroy your item once removed from the list, then you must
- * unreference your items twice. Note that reparenting is highly recommended
- * in most such cases (because it's a much cleaner way). However, if reparented
- * and the list itself gets destroyed, then the item will also get unreferenced.
+ * Prepending an item invalidates all existing iterators and puts them in an
+ * unspecified state. You'll need to recreate the iterator(s) when prepending
+ * items.
*
- * Reparenting indeed means reparenting. Okay? Loosing your parent reference
- * means loosing your reason of existance. So you'll get destroyed.
+ * When implementing, if you have to choose, make this one the fast one
*
- * You should not prepend, remove nor append items while iterating @self. There's
- * no guarantee whatsoever that existing iterators of @self will be valid after
- * this method returned.
- *
- * Implementers: if you have to choose, make this one the fast one
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer, type-implementer
**/
void
tny_list_prepend (TnyList *self, GObject* item)
@@ -97,40 +99,30 @@
/**
* tny_list_append:
- * @self: A #TnyList instance
- * @item: the item to append
+ * @self: A #TnyList
+ * @item (type-parameter G): the item to prepend
*
- * Appends an item to a list. You can only append items that inherit from the
- * GObject base item. That's because the tinymail list infrastructure does
- * reference counting. It effectively means that indeed you can't use non
- * GObject types in a tinymail list. But there's not a single situation where
- * you must do that. If you must store a non GObject in a list, you shouldn't
- * use the tinymail infrastructure for this. Consider using a doubly linked list
- * or a pointer array or any other list-type available on your development
- * platform.
+ * Appends an item to a list. You can only prepend items that inherit from the
+ * GObject base item. That's because Tinymail's list infrastructure does
+ * reference counting. Consider using a doubly linked list, a pointer array or
+ * any other list-type available on your development platform for non-GObject
+ * lists.
*
- * However, tinymail lists can cope with any valid GObject. Not just the
- * GObjects implemented by the tinymail framework.
+ * The @item you add will get a reference added by @self, with @self claiming
+ * ownership of @item. When @self is finalised, that reference is taken from
+ * @item.
*
- * All reference handling in tinymail is reference neutral. Also the lists. This
- * means that if your plan is to reparent the item to the list, that you should
- * take care of that by, after prepending or appending it, unreferencing it to
- * get rid of its initial reference. If you don't want to reparent, but you do
- * want to destroy your item once removed from the list, then you must
- * unreference your items twice. Note that reparenting is highly recommended
- * in most such cases (because it's a much cleaner way). However, if reparented
- * and the list itself gets destroyed, then the item will also get unreferenced.
+ * Appending an item invalidates all existing iterators and puts them in an
+ * unspecified state. You'll need to recreate the iterator(s) when appending
+ * items.
*
- * Reparenting indeed means reparenting. Okay? Loosing your parent reference
- * means loosing your reason of existance. So you'll get destroyed.
+ * When implementing, if you have to choose, make the prepend one the fast one
*
- * You should not prepend, remove nor append items while iterating @self. There's
- * no guarantee whatsoever that existing iterators of @self will be valid after
- * this method returned.
- *
- * Implementers: if you have to choose, make the prepend one the fast one
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer, type-implementer
**/
-void
+ void
tny_list_append (TnyList *self, GObject* item)
{
#ifdef DBC /* require */
@@ -152,18 +144,20 @@
/**
* tny_list_remove:
- * @self: A #TnyList instance
- * @item: the item to remove
+ * @self: A #TnyList
+ * @item (type-parameter G): the item to remove
*
- * Removes an item from a list. Removing a item might invalidate all existing
- * iterators or put them in an unknown and unspecified state. You'll need to
- * recreate the iterator(s) if you removed an item.
+ * Removes an item from a list. Removing a item invalidates all existing
+ * iterators and puts them in an unspecified state. You'll need to recreate
+ * the iterator(s) when removing an item.
*
- * If you want to clear a list, consider using the tny_list_foreach or simply
+ * If you want to clear a list, consider using the tny_list_foreach() or simply
* destroy the list instance and construct a new one. If you want to remove
* specific items from a list, consider using a second list. You should not
- * attempt to remove items from a list while an (any) iterator is active on the
+ * attempt to remove items from a list while an iterator is active on the
* same list.
+ *
+ * Removing @item from @self will decrease the reference count of @item by one.
*
* Example (removing even items):
* <informalexample><programlisting>
@@ -196,12 +190,9 @@
* g_object_unref (G_OBJECT (toremovefrom));
* </programlisting></informalexample>
*
- * There's no guarantee whatsoever that existing iterators of @self will be
- * valid after this method returned.
- *
- * Note that if you didn't remove the initial reference when putting the item
- * in the list, this remove will not take care of that initial reference either.
- *
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer, type-implementer
**/
void
tny_list_remove (TnyList *self, GObject* item)
@@ -224,13 +215,13 @@
/**
* tny_list_remove_matches:
- * @self: A #TnyList instance
+ * @self: A #TnyList
* @matcher: a #TnyListMatcher to match @match_data against items
* @match_data: data used by the comparer to remove items
*
- * Removes items from a list. Removing a item might invalidate all existing
- * iterators or put them in an unknown and unspecified state. You'll need to
- * recreate the iterator(s) if you removed an item.
+ * Removes items from a list. Removing items invalidates all existing
+ * iterators and put them in an unknown and unspecified state. You'll need to
+ * recreate the iterator(s) when removing items.
*
* Example (items that match):
* <informalexample><programlisting>
@@ -295,17 +286,15 @@
/**
* tny_list_create_iterator:
- * @self: A #TnyList instance
+ * @self: A #TnyList
*
- * Creates a new iterator instance for the list. The initial position
- * of the iterator is the first element.
+ * Creates a new iterator instance for the list. The initial position of the
+ * iterator is the first element.
*
- * An iterator is a position indicator for a list. It keeps the position
- * state of a list iteration. The list itself does not keep any position
- * information. Consuming multiple iterator instances makes it possible to
- * have multiple list iterations simultanously (i.e. multiple threads or in
- * in a loop that simultanously works with multiple position states in a
- * single list).
+ * An iterator keeps a position state of a list iteration. The list itself does
+ * not keep any position information. Using multiple iterator instances makes
+ * it possible to have simultaneous list iterations (i.e. multiple threads or
+ * in a loop that uses with multiple position states in a single list).
*
* Example:
* <informalexample><programlisting>
@@ -318,26 +307,20 @@
* tny_iterator_next (iter2);
* tny_iterator_next (iter1);
* }
- * g_object_unref (G_OBJECT (iter1));
- * g_object_unref (G_OBJECT (iter2));
- * g_object_unref (G_OBJECT (list));
+ * g_object_unref (iter1);
+ * g_object_unref (iter2);
+ * g_object_unref (list);
* </programlisting></informalexample>
*
- * The reason why the method isn't called get_iterator is because it's a
- * object creation method (a factory method). It's not a property. It effectively
- * creates a new instance of an iterator. The returned iterator object should
+ * The reason why the method isn't called get_iterator is because it's a object
+ * creation method (a factory method). Therefore it's not a property. Instead
+ * it creates a new instance of an iterator. The returned iterator object should
* (therefore) be unreferenced after use.
*
- * Implementers: For custom lists you must create a private iterator type and
- * return a new instance of it. You shouldn't make the internal API of that type
- * public.
- *
- * The developer will always only use the TnyIterator interface API on instances
- * of your type. You must therefore return your private iterator type, that
- * implements TnyIterator, here.
- *
- * Return value: A new iterator for the list @self
- *
+ * returns (caller-owns) (type-parameter G): A new iterator for the list
+ * since: 1.0
+ * complexity: high
+ * audience: application-developer, type-implementer
**/
TnyIterator*
tny_list_create_iterator (TnyList *self)
@@ -360,12 +343,12 @@
/**
* tny_list_foreach:
- * @self: A #TnyList instance
+ * @self: A #TnyList
* @func: the function to call with each element's data.
* @user_data: user data to pass to the function.
*
- * Calls a function for each element in a #TnyList. It will use an internal
- * iteration which you don't have to worry about.
+ * Calls @func for each element in a #TnyList. It will use an internal iteration
+ * which you don't have to worry about as application developer.
*
* Example:
* <informalexample><programlisting>
@@ -390,10 +373,13 @@
* element last. If during the iteration you don't remove items, it's guaranteed
* that all current items will be iterated.
*
- * In the func implementation and during the foreach operation you shouldn't
+ * In the func implementation and during the foreach operation you must not
* append, remove nor prepend items to the list. In multithreaded environments
* it's advisable to introduce a lock when using this functionality.
*
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer, type-implementer
**/
void
tny_list_foreach (TnyList *self, GFunc func, gpointer user_data)
@@ -411,17 +397,18 @@
/**
* tny_list_copy:
- * @self: A #TnyList instance
+ * @self: A #TnyList
*
- * Creates a shallow copy of the list. It doesn't copy the items. It,
- * however, creates a new list with new references to the same
- * items. The items will get an extra reference added for the new list
- * being their second parent, setting their reference count to for
- * example two. Which means that both lists (the original and the
- * copy) must be unreferenced after use.
+ * Creates a shallow copy of @self: it doesn't copy the content of the items.
+ * It creates a new list with new references to the same items. The items will
+ * get an extra reference added for the new list being their second owner,
+ * setting their reference count to for example two. Which means that the
+ * returned value must be unreferenced after use.
*
- * Return value: A copy of this list
- *
+ * returns (caller-owns) (type-parameter G): A copy of this list
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer, type-implementer
**/
TnyList*
tny_list_copy (TnyList *self)
Index: libtinymail/tny-account.c
===================================================================
--- libtinymail/tny-account.c (revision 3137)
+++ libtinymail/tny-account.c (working copy)
@@ -17,6 +17,15 @@
* Boston, MA 02110-1301, USA.
*/
+/**
+ * TnyAccount:
+ *
+ * A abstract account type with API shared between #TnyStoreAccount and
+ * #TnyTransportAccount.
+ *
+ * free-function: g_object_unref
+ */
+
#include <config.h>
#include <tny-status.h>
@@ -33,12 +42,15 @@
/**
* tny_account_get_connection_policy:
- * @self: a #TnyAccount object
+ * @self: a #TnyAccount
*
* Get the connection policy for @self. You must unreference the returned
* value when you are finished with used it.
*
- * Return value: connection policy
+ * returns (caller-owns): connection policy
+ * since: 1.0
+ * complexity: high
+ * audience: application-developer, platform-developer
**/
TnyConnectionPolicy*
tny_account_get_connection_policy (TnyAccount *self)
@@ -61,10 +73,14 @@
/**
* tny_account_set_connection_policy:
- * @self: a #TnyAccount object
- * @policy: the #TnyConnectionStrategy
+ * @self: a #TnyAccount
+ * @policy: a #TnyConnectionStrategy
*
* Set the connection strategy for @self.
+ *
+ * since: 1.0
+ * complexity: high
+ * audience: application-developer, platform-developer
**/
void
tny_account_set_connection_policy (TnyAccount *self, TnyConnectionPolicy *policy)
@@ -86,14 +102,17 @@
/**
* tny_account_is_ready:
- * @self: a #TnyAccount object
+ * @self: a #TnyAccount
*
* Some implementations of #TnyAccount need registration in a subsystem or
* factory before they are not only valid instances, but also ready to use. For
* example before their connection-status-changed signal emissions are accurate.
* This boolean property will tell you if @self is ready for that.
*
- * Return value: whether @self is ready for use
+ * returns: TRUE if @self is ready for use, else FALSE
+ * since: 1.0
+ * complexity: high
+ * audience: platform-developer
**/
gboolean
tny_account_is_ready (TnyAccount *self)
@@ -115,13 +134,17 @@
/**
* tny_account_start_operation:
- * @self: a #TnyAccount object
- * @domain: the domain of the #TnyStatus instances that will happen in @status_callback
- * @code: the code of the #TnyStatus instances that will happen in @status_callback
+ * @self: a #TnyAccount
+ * @domain: the domain of the #TnyStatus that will happen in @status_callback
+ * @code: the code of the #TnyStatus that will happen in @status_callback
* @status_callback: status callback handler
* @status_user_data: the user-data to give to the @status_callback
*
- * Start an operation. This only works with methods that don't end with _async.
+ * Starts an operation. This only works for methods that don't end with _async.
+ *
+ * since: 1.0
+ * complexity: high
+ * audience: application-developer
**/
void
tny_account_start_operation (TnyAccount *self, TnyStatusDomain domain, TnyStatusCode code, TnyStatusCallback status_callback, gpointer status_user_data)
@@ -141,14 +164,18 @@
/**
* tny_account_stop_operation:
- * @self: a #TnyAccount object
- * @canceled: NULL or byref whether the operation got canceled
+ * @self: a #TnyAccount
+ * @cancelled (out): NULL or byref whether the operation got canceled
*
- * Stop the current operation. This only works with methods that don't end
+ * Stop the current operation. This only works for methods that don't end
* with _async.
+ *
+ * since: 1.0
+ * complexity: high
+ * audience: application-developer
**/
void
-tny_account_stop_operation (TnyAccount *self, gboolean *canceled)
+tny_account_stop_operation (TnyAccount *self, gboolean *cancelled)
{
#ifdef DBC /* require */
g_assert (TNY_IS_ACCOUNT (self));
@@ -165,22 +192,24 @@
/**
* tny_account_matches_url_string:
- * @self: a #TnyAccount object
+ * @self: a #TnyAccount
* @url_string: the url-string of the account to find
*
- * Find out whether the account matches a certain url_string.
+ * Returns whether the account's url-string matches @url_string.
*
- * Implementors: Be forgiving about things like passwords in the url_string:
+ * When implementing be forgiving about things like passwords in the url_string:
* while matching the folder, password and message-id pieces are insignificant.
*
* An example url_string can be imap://user:password server/INBOX/005. Only
* "imap://user server" is significant when searching. Also take a look at
- * RFC 1808 and RFC 4467 for more information on url_string formatting.
+ * RFC 1808 and RFC 4467 for more information on url-string formatting.
*
- * This method must be usable with and will be used for
- * tny_account_store_find_account.
+ * This method will be used by tny_account_store_find_account().
*
- * Return value: whether or not @self matches with @url_string.
+ * returns: TRUE if @self matches with @url_string, else FALSE
+ * since: 1.0
+ * complexity: high
+ * audience: application-developer, platform-developer
**/
gboolean
tny_account_matches_url_string (TnyAccount *self, const gchar *url_string)
@@ -204,10 +233,16 @@
/**
* tny_account_cancel:
- * @self: a #TnyAccount object
+ * @self: a #TnyAccount
*
* Try to cancel the current operation that is happening. This API, though,
- * guarantees nothing about any cancelations.
+ * makes no guarantees about any cancellations taking place (it's a try).
+ *
+ * Since relatively few guarantees can be made, using this API is not recommended.
+ *
+ * since: 1.0
+ * complexity: high
+ * audience: application-developer
**/
void
tny_account_cancel (TnyAccount *self)
@@ -227,7 +262,7 @@
/**
* tny_account_get_account_type:
- * @self: a #TnyAccount object
+ * @self: a #TnyAccount
*
* Get the account type of @self. There are two account types: a store and
* transport account type.
@@ -236,9 +271,12 @@
* IMAP and POP accounts.
*
* A transport account has a send method for sending #TnyMsg instances
- * using the transport implemented by the account (for example SMTP).
+ * using the transport layer the account uses. For example SMTP.
*
- * Return value: The account type
+ * returns: The account type
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
TnyAccountType
tny_account_get_account_type (TnyAccount *self)
@@ -261,11 +299,14 @@
/**
* tny_account_get_connection_status:
- * @self: a #TnyAccount object
+ * @self: a #TnyAccount
*
- * Get the connection status of @self
+ * Get the status of the connection for account @self.
*
- * Return value: the status of the connection
+ * returns: the status of the connection
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
TnyConnectionStatus
tny_account_get_connection_status (TnyAccount *self)
@@ -288,17 +329,22 @@
/**
* tny_account_get_id:
- * @self: a #TnyAccount object
+ * @self: a #TnyAccount
*
- * Get the unique id of @self
+ * Get the unique id of @self.
*
* A certainty you have about this property is that the id is unique in the
- * #TnyAccountStore. It doesn't have to be unique in the entire application.
+ * #TnyAccountStore that contains @self. It doesn't have to be unique in the
+ * entire application if you have multiple #TnyAccountStore instances (which
+ * is unlikely).
*
- * The format of the id isn't specified. The implementor of the #TnyAccountStore
+ * The format of the id isn't specified. The implementer of the #TnyAccountStore
* must set this id using tny_account_set_id.
*
- * Return value: Unique id
+ * returns: unique id
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
const gchar*
tny_account_get_id (TnyAccount *self)
@@ -322,11 +368,14 @@
/**
* tny_account_set_name:
- * @self: a #TnyAccount object
+ * @self: a #TnyAccount
* @name: the name
*
* Set the account's human readable name
*
+ * since: 1.0
+ * complexity: low
+ * audience: platform-developer
**/
void
tny_account_set_name (TnyAccount *self, const gchar *name)
@@ -357,7 +406,7 @@
/**
* tny_account_set_secure_auth_mech:
- * @self: a #TnyAccount object
+ * @self: a #TnyAccount
* @mech: the authentication mechanism
*
* Set the account's secure authentication mechanism. The possible values depend on
@@ -380,7 +429,10 @@
*
* Other relevant standards:
* - <ulink url="http://www.faqs.org/rfcs/rfc1731.html";>RFC 1731 - IMAP4 Authentication Mechanisms</ulink>
- *
+ *
+ * since: 1.0
+ * complexity: high
+ * audience: platform-developer
**/
void
tny_account_set_secure_auth_mech (TnyAccount *self, const gchar *mech)
@@ -403,13 +455,16 @@
/**
* tny_account_set_id:
- * @self: a #TnyAccount object
+ * @self: a #TnyAccount
* @id: the id
*
* Set the unique id of the account. You need to set this property before you
* can start using the account. The id must be unique in a #TnyAccountStore and
* is typically set in the implementation of a #TnyAccountStore.
- *
+ *
+ * since: 1.0
+ * complexity: high
+ * audience: platform-developer
**/
void
tny_account_set_id (TnyAccount *self, const gchar *id)
@@ -432,7 +487,7 @@
/**
* tny_account_set_forget_pass_func:
- * @self: a #TnyAccount object
+ * @self: a #TnyAccount
* @forget_pass_func: a pointer to the function
*
* Set the function that will be called in case the password was wrong and
@@ -468,6 +523,10 @@
* ...
* }
* </programlisting></informalexample>
+ *
+ * since: 1.0
+ * complexity: high
+ * audience: platform-developer
**/
void
tny_account_set_forget_pass_func (TnyAccount *self, TnyForgetPassFunc forget_pass_func)
@@ -488,11 +547,11 @@
/**
* tny_account_get_forget_pass_func:
- * @self: a #TnyAccount object
+ * @self: a #TnyAccount
*
- * Get a pointer to the forget-password function
+ * Get a pointer to the forget-password function for @self.
*
- * Return value: A pointer to the forget-password function
+ * returns: A pointer to the forget-password function
**/
TnyForgetPassFunc
tny_account_get_forget_pass_func (TnyAccount *self)
@@ -514,17 +573,22 @@
/**
* tny_account_set_url_string:
- * @self: a #TnyAccount object
+ * @self: a #TnyAccount
* @url_string: the url string (ex. mbox://path)
*
* Set the url string of @self (RFC 1808). You don't need to use this for imap
- * and pop where you can use the simplified API (set_proto, set_hostname, etc).
- * This property is typically set in the implementation of a #TnyAccountStore.
+ * and pop where you can use the simplified API (tny_account_set_proto(),
+ * tny_account_set_hostname(), etc). This property is typically set in the
+ * implementation of a #TnyAccountStore.
*
- * For example the url_string for an SMTP account that uses SSL with authentication
+ * For example the url-string for an SMTP account that uses SSL with authentication
* type PLAIN: smtp://user;auth=PLAIN smtp server com/;use_ssl=wrapped
*
- * Don't forget to set the name, type and proto setting of the account too.
+ * Don't forget to set the name, type and protocol setting of the account too.
+ *
+ * since: 1.0
+ * complexity: high
+ * audience: platform-developer
**/
void
tny_account_set_url_string (TnyAccount *self, const gchar *url_string)
@@ -552,13 +616,16 @@
/**
* tny_account_set_proto:
- * @self: a #TnyAccount object
+ * @self: a #TnyAccount
* @proto: the protocol (ex. "imap")
*
* Set the protocol of @self. You need to set this property before you can start
* using the account. This property is typically set in the implementation
* of a #TnyAccountStore.
- *
+ *
+ * since: 1.0
+ * complexity: high
+ * audience: platform-developer
**/
void
tny_account_set_proto (TnyAccount *self, const gchar *proto)
@@ -581,13 +648,16 @@
/**
* tny_account_set_user:
- * @self: a #TnyAccount object
+ * @self: a #TnyAccount
* @user: the username
*
- * Set the user or login of @self. You need to set this property before you
- * can start using the account. This property is typically set in the
- * implementation of a #TnyAccountStore.
+ * Set the user or login of account @self. You need to set this property
+ * before you can start using the account. This property is typically set
+ * in the implementation of a #TnyAccountStore.
*
+ * since: 1.0
+ * complexity: high
+ * audience: platform-developer
**/
void
tny_account_set_user (TnyAccount *self, const gchar *user)
@@ -611,13 +681,16 @@
/**
* tny_account_set_hostname:
- * @self: a #TnyAccount object
+ * @self: a #TnyAccount
* @host: the hostname
*
- * Set the hostname of @self. You need to set this property before you can start
- * using the account. This property is typically set in the implementation of a
- * #TnyAccountStore.
+ * Set the hostname of account @self. You need to set this property before you
+ * can start using the account. This property is typically set in the
+ * implementation of a #TnyAccountStore.
*
+ * since: 1.0
+ * complexity: high
+ * audience: platform-developer
**/
void
tny_account_set_hostname (TnyAccount *self, const gchar *host)
@@ -643,12 +716,15 @@
/**
* tny_account_set_port:
- * @self: a #TnyAccount object
- * @port: the port to connect to on the hostname
+ * @self: a #TnyAccount
+ * @port: the port to connect to on the hostname of @self
*
* Set the port of @self. If you don't set this property, the default port for
- * the protocol will be used (for example 143 and 993 for IMAP and 110 for POP3).
+ * the protocol will be used (for example 143, 993 for IMAP and 110, 995 for POP3).
*
+ * since: 1.0
+ * complexity: high
+ * audience: platform-developer
**/
void
tny_account_set_port (TnyAccount *self, guint port)
@@ -669,7 +745,7 @@
/**
* tny_account_set_pass_func:
- * @self: a #TnyAccount object
+ * @self: a #TnyAccount
* @get_pass_func: a pointer to the function
*
* Set the function that will be called when the password is needed. The
@@ -680,6 +756,8 @@
* property is typically set in the implementation of a #TnyAccountStore. Set
* this property as the last of all properties that you will set to an account
* in the #TnyAccountStore.
+ *
+ * If possible, use the mlock() syscall on this memory.
*
* Also see #TnyGetPassFunc for more information about the function itself.
*
@@ -695,7 +773,8 @@
* pwdgetter = tny_platform_factory_new_password_getter (platfact);
* retval = (gchar*) tny_password_getter_get_password (pwdgetter,
* tny_account_get_id (account), prompt, cancel);
- * g_object_unref (G_OBJECT (pwdgetter));
+ * mlock (retval, strlen (retval));
+ * g_object_unref (pwdgetter);
* return retval;
* }
* static void
@@ -706,10 +785,14 @@
* tny_account_set_forget_pass_func (account, per_account_forget_pass_func);
* tny_account_set_pass_func (account, per_account_get_pass_func);
* tny_list_prepend (list, (GObject*)account);
- * g_object_unref (G_OBJECT (account));
+ * g_object_unref (account);
* ...
* }
* </programlisting></informalexample>
+ *
+ * since: 1.0
+ * complexity: high
+ * audience: platform-developer
**/
void
tny_account_set_pass_func (TnyAccount *self, TnyGetPassFunc get_pass_func)
@@ -730,12 +813,14 @@
/**
* tny_account_get_proto:
- * @self: a #TnyAccount object
+ * @self: a #TnyAccount
*
* Get the protocol of @self. The returned value should not be freed.
*
- * Return value: the protocol as a read-only string
- *
+ * returns: the protocol as a read-only string
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
const gchar*
tny_account_get_proto (TnyAccount *self)
@@ -759,16 +844,19 @@
/**
* tny_account_get_url_string:
- * @self: a #TnyAccount object
+ * @self: a #TnyAccount
*
- * Get the url string of @self or NULL if it's impossible to determine the url
- * string of @self. If not NULL, the returned value must be freed.
+ * Get the url-string of account @self or NULL if it's impossible to determine
+ * the url-string of @self. If not NULL, the returned value must be freed.
*
* The url string is specified in RFC 1808 and looks for example like this:
* imap://user hostname Note that it doesn't necessarily contain the password
- * of the IMAP account.
+ * of the account.
*
- * Return value: the url string or NULL.
+ * returns (null-ok) (caller-owns): the url-string or NULL.
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
gchar*
tny_account_get_url_string (TnyAccount *self)
@@ -784,7 +872,7 @@
#ifdef DBC /* ensure */
if (retval)
- g_assert (strstr (retval, "://") != NULL);
+ g_assert (strstr (retval, ":") != NULL);
#endif
return retval;
@@ -793,13 +881,15 @@
/**
* tny_account_get_user:
- * @self: a #TnyAccount object
+ * @self: a #TnyAccount
*
- * Get the user or login of @self. The returned value should not be freed. The
- * returned value van be NULL in case of no user.
+ * Get the user or login of account @self. The returned value should
+ * not be freed. The returned value can be NULL.
*
- * Return value: the user as a read-only string
- *
+ * returns: the user as a read-only string
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
const gchar*
tny_account_get_user (TnyAccount *self)
@@ -821,13 +911,15 @@
/**
* tny_account_get_name:
- * @self: a #TnyAccount object
+ * @self: a #TnyAccount
*
- * Get the human readable name of @self. The returned value should not
- * be freed. The returned value van be NULL in case of no human reabable name.
+ * Get the human readable name of account self The returned value should not
+ * be freed. The returned value can be NULL.
*
- * Return value: the human readable name as a read-only string
- *
+ * returns: the human readable name as a read-only string
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
const gchar*
tny_account_get_name (TnyAccount *self)
@@ -850,13 +942,16 @@
/**
* tny_account_get_secure_auth_mech:
- * @self: a #TnyAccount object
+ * @self: a #TnyAccount
*
- * Get the secure authentication mechanism for this account. Default is "PLAIN". The
- * returned value can be NULL, in which case a undefined default is used.
+ * Get the secure authentication mechanism for this account. Default is "PLAIN".
+ * The returned value can be NULL, in which case a undefined default is used.
+ * The returned value should not be freed.
*
- * Return value: the authentication mechanism as a read-only string
- *
+ * returns: the authentication mechanism as a read-only string
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
const gchar*
tny_account_get_secure_auth_mech (TnyAccount *self)
@@ -885,8 +980,10 @@
* returned value can be NULL, in which case no hostname is set (for example
* for a local account).
*
- * Return value: the hostname as a read-only string
- *
+ * returns: the hostname as a read-only string
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
const gchar*
tny_account_get_hostname (TnyAccount *self)
@@ -909,11 +1006,14 @@
/**
* tny_account_get_port:
- * @self: a #TnyAccount object
+ * @self: a #TnyAccount
*
* Get the port of @self.
*
- * Return value: the port
+ * returns: the port
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
guint
tny_account_get_port (TnyAccount *self)
@@ -934,11 +1034,14 @@
}
/**
* tny_account_get_pass_func:
- * @self: a #TnyAccount object
+ * @self: a #TnyAccount
*
* Get a pointer to the get-password function
*
- * Return value: A pointer to the get-password function
+ * returns: A pointer to the get-password function
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
TnyGetPassFunc
tny_account_get_pass_func (TnyAccount *self)
@@ -974,6 +1077,10 @@
* @user_data: user data set when the signal handler was connected.
*
* Emitted when the connection status of an account changes.
+ *
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
tny_account_signals[TNY_ACCOUNT_CONNECTION_STATUS_CHANGED] =
g_signal_new ("connection_status_changed",
@@ -991,7 +1098,11 @@
* @self: the object on which the signal is emitted
* @user_data: user data set when the signal handler was connected.
*
- * Emitted when the account changes.
+ * Emitted when one of the account's properties changes.
+ *
+ * since: 1.0
+ * complexity: low
+ * audience: application-developer
**/
tny_account_signals[TNY_ACCOUNT_CHANGED] =
g_signal_new ("changed",
@@ -1011,7 +1122,7 @@
*
* GType system helper function
*
- * Return value: a GType
+ * returns: a #GType
**/
GType
tny_account_get_type (void)
@@ -1047,7 +1158,7 @@
*
* GType system helper function
*
- * Return value: a GType
+ * returns: a #GType
**/
GType
tny_account_type_get_type (void)
@@ -1071,7 +1182,7 @@
*
* GType system helper function
*
- * Return value: a GType
+ * returns: a #GType
**/
GType
tny_account_signal_type_get_type (void)
@@ -1094,7 +1205,7 @@
*
* GType system helper function
*
- * Return value: a GType
+ * returns: a #GType
**/
GType
tny_connection_status_get_type (void)
Index: libtinymail/tny-connection-policy.c
===================================================================
--- libtinymail/tny-connection-policy.c (revision 3137)
+++ libtinymail/tny-connection-policy.c (working copy)
@@ -17,7 +17,17 @@
* Boston, MA 02110-1301, USA.
*/
+/**
+ * TnyConnectionPolicy:
+ *
+ * A connection policy. For example to attempt to reconnect or to fail
+ * in case of connectivity problems.
+ *
+ * free-function: g_object_unref
+ */
+
#include <config.h>
+
#include <tny-account.h>
#include <tny-folder.h>
#include <tny-connection-policy.h>
@@ -26,12 +36,21 @@
/**
* tny_connection_policy_set_current:
- * @self: A #TnyConnectionPolicy instance
- * @account: the current #TnyAccount instance
- * @folder: the current #TnyFolder instance
+ * @self: a #TnyConnectionPolicy
+ * @account: a #TnyAccount
+ * @folder: a #TnyFolder
*
- * Used to set the current situation (in case @self wants to restore this
- * situation in case of a connection event).
+ * Set the current situation of @self (in case @self wants to restore the
+ * situation when @account reconnected).
+ *
+ * Tinymail's internal administration will call this function whenever
+ * tny_folder_refresh or tny_folder_refresh_async get called. It's highly
+ * recommended to use g_object_weak_ref when setting the current and
+ * g_object_weak_unref when unsetting the current or when finalising @self.
+ *
+ * since: 1.0
+ * complexity: high
+ * audience: platform-developer, application-developer, type-implementer
**/
void
tny_connection_policy_set_current (TnyConnectionPolicy *self, TnyAccount *account, TnyFolder *folder)
@@ -51,10 +70,14 @@
/**
* tny_connection_policy_on_connect:
- * @self: A #TnyConnectionPolicy instance
- * @account: a #TnyAccount instance
+ * @self: A #TnyConnectionPolicy
+ * @account: a #TnyAccount
*
- * Happens when @account got connected.
+ * Called when @account got connected.
+ *
+ * since: 1.0
+ * complexity: high
+ * audience: platform-developer, application-developer, type-implementer
**/
void
tny_connection_policy_on_connect (TnyConnectionPolicy *self, TnyAccount *account)
@@ -73,10 +96,14 @@
/**
* tny_connection_policy_on_disconnect:
- * @self: A #TnyConnectionPolicy instance
- * @account: a #TnyAccount instance
+ * @self: A #TnyConnectionPolicy
+ * @account: a #TnyAccount
*
- * Happens when @account got disconnected.
+ * Called when @account got disconnected.
+ *
+ * since: 1.0
+ * complexity: high
+ * audience: platform-developer, application-developer, type-implementer
**/
void
tny_connection_policy_on_disconnect (TnyConnectionPolicy *self, TnyAccount *account)
@@ -95,10 +122,15 @@
/**
* tny_connection_policy_on_connection_broken:
- * @self: A #TnyConnectionPolicy instance
- * @account: a #TnyAccount instance
+ * @self: A #TnyConnectionPolicy
+ * @account: a #TnyAccount
*
- * Happens when @account got connected.
+ * Called when @account's connection broke. For example when a connection
+ * timeout occurred.
+ *
+ * since: 1.0
+ * complexity: high
+ * audience: platform-developer, application-developer, type-implementer
**/
void
tny_connection_policy_on_connection_broken (TnyConnectionPolicy *self, TnyAccount *account)
Index: libtinymail/tny-account.h
===================================================================
--- libtinymail/tny-account.h (revision 3137)
+++ libtinymail/tny-account.h (working copy)
@@ -107,7 +107,7 @@
void (*cancel_func) (TnyAccount *self);
gboolean (*matches_url_string_func) (TnyAccount *self, const gchar *url_string);
void (*start_operation_func) (TnyAccount *self, TnyStatusDomain domain, TnyStatusCode code, TnyStatusCallback status_callback, gpointer status_user_data);
- void (*stop_operation_func) (TnyAccount *self, gboolean *canceled);
+ void (*stop_operation_func) (TnyAccount *self, gboolean *cancelled);
gboolean (*is_ready_func) (TnyAccount *self);
TnyConnectionPolicy* (*get_connection_policy_func) (TnyAccount *self);
void (*set_connection_policy_func) (TnyAccount *self, TnyConnectionPolicy *policy);
@@ -147,7 +147,7 @@
void tny_account_cancel (TnyAccount *self);
gboolean tny_account_matches_url_string (TnyAccount *self, const gchar *url_string);
void tny_account_start_operation (TnyAccount *self, TnyStatusDomain domain, TnyStatusCode code, TnyStatusCallback status_callback, gpointer status_user_data);
-void tny_account_stop_operation (TnyAccount *self, gboolean *canceled);
+void tny_account_stop_operation (TnyAccount *self, gboolean *cancelled);
gboolean tny_account_is_ready (TnyAccount *self);
TnyConnectionPolicy* tny_account_get_connection_policy (TnyAccount *self);
void tny_account_set_connection_policy (TnyAccount *self, TnyConnectionPolicy *policy);
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
