From cb9add11df21b1d5651cbcd0de1497e586bd324f Mon Sep 17 00:00:00 2001
From: Simon Morlat <simon.morlat@linphone.org>
Date: Mon, 31 Jan 2011 17:06:34 +0100
Subject: [PATCH] improve documentation

---
 coreapi/help/doxygen.dox |  7 +++++++
 coreapi/linphonecore.h   | 34 +++++++++++++++++++++++-----------
 2 files changed, 30 insertions(+), 11 deletions(-)

diff --git a/coreapi/help/doxygen.dox b/coreapi/help/doxygen.dox
index 8707785b2..32ed3da1a 100644
--- a/coreapi/help/doxygen.dox
+++ b/coreapi/help/doxygen.dox
@@ -34,6 +34,13 @@
 
 /**
  * @defgroup call_control Placing and receiving calls
+ *
+ * The #LinphoneCall object represents an incoming or outgoing call managed by the #LinphoneCore.
+ * Outgoing calls can be created using linphone_core_invite() or linphone_core_invite_address(), while incoming calls are notified to the application
+ * through the LinphoneCoreVTable::call_state_changed callback.
+ *
+ * See the basic call \ref basic_call_tutorials "tutorial".
+ *
 **/
 
 /**
diff --git a/coreapi/linphonecore.h b/coreapi/linphonecore.h
index 04be47483..2170459e5 100644
--- a/coreapi/linphonecore.h
+++ b/coreapi/linphonecore.h
@@ -185,6 +185,7 @@ void linphone_call_params_destroy(LinphoneCallParams *cp);
 
 /**
  * Enum describing failure reasons.
+ * @ingroup initializing
 **/
 enum _LinphoneReason{
 	LinphoneReasonNone,
@@ -203,8 +204,13 @@ const char *linphone_reason_to_string(LinphoneReason err);
 struct _LinphoneCall;
 typedef struct _LinphoneCall LinphoneCall;
 
+/**
+ * LinphoneCallState enum represents the different state a call can reach into.
+ * The application is notified of state changes through the LinphoneCoreVTable::call_state_changed callback.
+ * @ingroup call_control
+**/
 typedef enum _LinphoneCallState{
-	LinphoneCallIdle,
+	LinphoneCallIdle,					/**<Initial call state */
 	LinphoneCallIncomingReceived, /**<This is a new incoming call */
 	LinphoneCallOutgoingInit, /**<An outgoing call is started */
 	LinphoneCallOutgoingProgress, /**<An outgoing call is in progress */
@@ -302,11 +308,11 @@ typedef struct _LinphoneProxyConfig LinphoneProxyConfig;
  * LinphoneRegistrationState describes proxy registration states.
 **/
 typedef enum _LinphoneRegistrationState{
-	LinphoneRegistrationNone,
-	LinphoneRegistrationProgress,
-	LinphoneRegistrationOk,
-	LinphoneRegistrationCleared,
-	LinphoneRegistrationFailed
+	LinphoneRegistrationNone, /**<Initial state for registrations */
+	LinphoneRegistrationProgress, /**<Registration is in progress */
+	LinphoneRegistrationOk,	/**< Registration is successful */
+	LinphoneRegistrationCleared, /**< Unregistration succeeded */
+	LinphoneRegistrationFailed	/**<Registration failed */
 }LinphoneRegistrationState;
 
 /**
@@ -485,6 +491,17 @@ void * linphone_chat_room_get_user_data(LinphoneChatRoom *cr);
 /**
  * @}
  */
+
+
+/**
+ * @addtogroup initializing
+ * @{
+**/
+
+/**
+ * LinphoneGlobalState describes the global state of the LinphoneCore object.
+ * It is notified via the LinphoneCoreVTable::global_state_changed
+**/
 typedef enum _LinphoneGlobalState{
 	LinphoneGlobalOff,
 	LinphoneGlobalStartup,
@@ -494,11 +511,6 @@ typedef enum _LinphoneGlobalState{
 
 const char *linphone_global_state_to_string(LinphoneGlobalState gs);
 
-/**
- * @addtogroup initializing
- * @{
-**/
-
 
 /**Call state notification callback prototype*/
 typedef void (*LinphoneGlobalStateCb)(struct _LinphoneCore *lc, LinphoneGlobalState gstate, const char *message);