New documentation style
- From: Philip Van Hoof <spam pvanhoof be>
- To: tinymail-devel-list gnome org
- Subject: New documentation style
- Date: Sun, 16 Dec 2007 16:43:38 +0100
Hf
--
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-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,15 @@
* Boston, MA 02110-1301, USA.
*/
+/**
+ * TnyIterator:
+ *
+ * Iterates a #TnyList
+ *
+ * free-function: g_object_unref
+ *
+ **/
+
#include <config.h>
#include <tny-iterator.h>
@@ -24,10 +33,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 +56,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 +80,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 +103,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 +130,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 +162,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 +178,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 +202,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-list.c
===================================================================
--- libtinymail/tny-list.c (revision 3137)
+++ libtinymail/tny-list.c (working copy)
@@ -22,12 +22,24 @@
#include <tny-list.h>
/**
+ * TnyList:
+ *
+ * A list of things
+ *
+ * free-function: g_object_unref
+ * type-parameter: G
+ */
+
+/**
* 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
* 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,14 @@
* Boston, MA 02110-1301, USA.
*/
+/**
+ * TnyAccount:
+ *
+ * A account
+ *
+ * free-function: g_object_unref
+ */
+
#include <config.h>
#include <tny-status.h>
@@ -33,12 +41,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 +72,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 +101,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 +133,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 +163,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 +191,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 +232,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 +261,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 +270,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 +298,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 +328,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 +367,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 +405,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 +428,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)
@@ -409,7 +460,10 @@
* 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 +486,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 +522,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 +546,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 +572,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
* 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 +615,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 +647,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 +680,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 +715,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 +744,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 +755,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 +772,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 +784,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 +812,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 +843,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 +871,7 @@
#ifdef DBC /* ensure */
if (retval)
- g_assert (strstr (retval, "://") != NULL);
+ g_assert (strstr (retval, ":") != NULL);
#endif
return retval;
@@ -793,13 +880,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 +910,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 +941,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 +979,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 +1005,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 +1033,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 +1076,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 +1097,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 +1121,7 @@
*
* GType system helper function
*
- * Return value: a GType
+ * returns: a #GType
**/
GType
tny_account_get_type (void)
@@ -1047,7 +1157,7 @@
*
* GType system helper function
*
- * Return value: a GType
+ * returns: a #GType
**/
GType
tny_account_type_get_type (void)
@@ -1071,7 +1181,7 @@
*
* GType system helper function
*
- * Return value: a GType
+ * returns: a #GType
**/
GType
tny_account_signal_type_get_type (void)
@@ -1094,7 +1204,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)
@@ -26,12 +26,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 +60,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 +86,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 +112,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]
