/dev/tomkiewicz/e2ee: e322f9c8f3e9: Fill comments for E2EE branch

[Tomasz Wasilczyk]

Changeset: e322f9c8f3e91f77e727ba96aba70244eb7d29e0
Author:	 Tomasz Wasilczyk <twasilczyk at pidgin.im>
Date:	 2013-10-24 18:17 +0200
Branch:	 default
URL: https://hg.pidgin.im/dev/tomkiewicz/e2ee/rev/e322f9c8f3e9

Description:

Fill comments for E2EE branch

diffstat:

 libpurple/conversation.h |   13 +++++
 libpurple/e2ee.h         |  120 +++++++++++++++++++++++++++++++++++++++++++++++
 libpurple/util.h         |   13 +++++
 3 files changed, 146 insertions(+), 0 deletions(-)

diffs (237 lines):

diff --git a/libpurple/conversation.h b/libpurple/conversation.h
--- a/libpurple/conversation.h
+++ b/libpurple/conversation.h
@@ -407,10 +407,23 @@ void purple_conversation_set_name(Purple
  */
 const char *purple_conversation_get_name(const PurpleConversation *conv);
 
+/**
+ * Sets current E2EE state for the conversation.
+ *
+ * @param conv  The conversation.
+ * @param state The E2EE state.
+ */
 void
 purple_conversation_set_e2ee_state(PurpleConversation *conv,
 	PurpleE2eeState *state);
 
+/**
+ * Gets current conversation's E2EE state.
+ *
+ * @param conv The conversation.
+ *
+ * @return Current E2EE state for conversation.
+ */
 PurpleE2eeState *
 purple_conversation_get_e2ee_state(PurpleConversation *conv);
 
diff --git a/libpurple/e2ee.h b/libpurple/e2ee.h
--- a/libpurple/e2ee.h
+++ b/libpurple/e2ee.h
@@ -43,28 +43,84 @@ G_BEGIN_DECLS
 /**************************************************************************/
 /*@{*/
 
+/**
+ * Creates new E2EE state.
+ *
+ * State objects are global (shared between multiple conversations).
+ *
+ * @param provider The E2EE provider that created this state.
+ *
+ * @return New E2EE state.
+ */
 PurpleE2eeState *
 purple_e2ee_state_new(PurpleE2eeProvider *provider);
 
+/**
+ * Increment the reference count.
+ *
+ * @param state The E2EE state.
+ */
 void
 purple_e2ee_state_ref(PurpleE2eeState *state);
 
+/**
+ * Decrement the reference count.
+ *
+ * If the reference count reaches zero, the state will be freed.
+ *
+ * @param state The E2EE state.
+ *
+ * @return @a state or @c NULL if the reference count reached zero.
+ */
 PurpleE2eeState *
 purple_e2ee_state_unref(PurpleE2eeState *state);
 
+/**
+ * Gets the provider of specified E2EE state.
+ *
+ * @param state The E2EE state.
+ *
+ * @return The provider for this state.
+ */
 PurpleE2eeProvider *
 purple_e2ee_state_get_provider(PurpleE2eeState *state);
 
+/**
+ * Sets the name for the E2EE state.
+ *
+ * @param state The E2EE state.
+ * @param name  The localized name.
+ */
 void
 purple_e2ee_state_set_name(PurpleE2eeState *state, const gchar *name);
 
+/**
+ * Gets the name of the E2EE state.
+ *
+ * @param state The E2EE state.
+ *
+ * @return The localized name.
+ */
 const gchar *
 purple_e2ee_state_get_name(PurpleE2eeState *state);
 
+/**
+ * Sets the icon for the E2EE state.
+ *
+ * @param state      The E2EE state.
+ * @param stock_icon The stock icon identifier.
+ */
 void
 purple_e2ee_state_set_stock_icon(PurpleE2eeState *state,
 	const gchar *stock_icon);
 
+/**
+ * Gets the icon of the E2EE state.
+ *
+ * @param state The E2EE state.
+ *
+ * @return The stock icon identifier.
+ */
 const gchar *
 purple_e2ee_state_get_stock_icon(PurpleE2eeState *state);
 
@@ -76,31 +132,95 @@ purple_e2ee_state_get_stock_icon(PurpleE
 /**************************************************************************/
 /*@{*/
 
+/**
+ * Creates new E2EE provider.
+ *
+ * @return New E2EE provider.
+ */
 PurpleE2eeProvider *
 purple_e2ee_provider_new(void);
 
+/**
+ * Destroys the E2EE provider.
+ *
+ * The provider have to be unregistered prior.
+ *
+ * @param provider The provider.
+ */
 void
 purple_e2ee_provider_free(PurpleE2eeProvider *provider);
 
+/**
+ * Registers the E2EE provider.
+ *
+ * Currently, there is no support for multiple E2EE providers - only the first
+ * one is registered.
+ *
+ * @param provider The E2EE provider.
+ *
+ * @return @c TRUE, if the provider was successfully registered,
+ *         @c FALSE otherwise.
+ */
 gboolean
 purple_e2ee_provider_register(PurpleE2eeProvider *provider);
 
+/**
+ * Unregisters the E2EE provider.
+ *
+ * @param provider The E2EE provider.
+ */
 void
 purple_e2ee_provider_unregister(PurpleE2eeProvider *provider);
 
+/**
+ * Gets main E2EE provider.
+ *
+ * @return The main E2EE provider.
+ */
 PurpleE2eeProvider *
 purple_e2ee_provider_get_main(void);
 
+/**
+ * Sets the name for the E2EE provider.
+ *
+ * @param provider The E2EE provider.
+ * @param name     The localized name.
+ */
 void
 purple_e2ee_provider_set_name(PurpleE2eeProvider *provider, const gchar *name);
 
+/**
+ * Gets the name of the E2EE provider.
+ *
+ * @param provider The E2EE provider.
+ *
+ * @return The localized name of specified E2EE provider.
+ */
 const gchar *
 purple_e2ee_provider_get_name(PurpleE2eeProvider *provider);
 
+/**
+ * Sets the conversation menu callback for the E2EE provider.
+ *
+ * The function is called, when user extends the E2EE menu for the conversation
+ * specified in its parameter.
+ *
+ * Function should return the GList of PurpleMenuAction objects.
+ *
+ * @param provider     The E2EE provider.
+ * @param conv_menu_cb The callback.
+ */
 void
 purple_e2ee_provider_set_conv_menu_cb(PurpleE2eeProvider *provider,
 	PurpleE2eeConvMenuCallback conv_menu_cb);
 
+/**
+ * Gets the conversation menu callback of the E2EE provider.
+ *
+ * @param provider The E2EE provider.
+ *
+ * @return The callback.
+ */
 PurpleE2eeConvMenuCallback
 purple_e2ee_provider_get_conv_menu_cb(PurpleE2eeProvider *provider);
 
diff --git a/libpurple/util.h b/libpurple/util.h
--- a/libpurple/util.h
+++ b/libpurple/util.h
@@ -153,9 +153,22 @@ void purple_menu_action_set_data(PurpleM
  */
 void purple_menu_action_set_children(PurpleMenuAction *act, GList *children);
 
+/**
+ * Sets the icon for the PurpleMenuAction.
+ *
+ * @param act    The menu action.
+ * @param strock The stock icon identifier.
+ */
 void purple_menu_action_set_stock_icon(PurpleMenuAction *act,
 	const gchar *stock);
 
+/**
+ * Gets the stock icon of the PurpleMenuAction.
+ *
+ * @param act The menu action.
+ *
+ * @return The stock icon identifier.
+ */
 const gchar *
 purple_menu_action_get_stock_icon(PurpleMenuAction *act);