4 files changed, 21 insertions, 27 deletions

diff --git a/src/arm/arm.h b/src/arm/arm.h
index bf2f7e797..e5a2f9b5e 100644
--- a/src/arm/arm.h
+++ b/src/arm/arm.h
@@ -60,11 +60,12 @@ struct GNUNET_ARM_Message
    * Reply to client, type is #GNUNET_MESSAGE_TYPE_ARM_RESULT or
    * #GNUNET_MESSAGE_TYPE_ARM_LIST_RESULT.
    * OR
-   * Request from client, type is #GNUNET_MESSAGE_TYPE_ARM_REQUEST
+   * Request from client, type is #GNUNET_MESSAGE_TYPE_ARM_START or
+   * #GNUNET_MESSAGE_TYPE_ARM_STOP.
    */
   struct GNUNET_MessageHeader header;
 
-  /** 
+  /**
    * For alignment.
    */
   uint32_t reserved;
@@ -87,12 +88,12 @@ struct GNUNET_ARM_ResultMessage
 {
 
   /**
-   * Reply to client, of type is GNUNET_MESSAGE_TYPE_ARM_RESULT, with an ID.
+   * Reply to client, of type is #GNUNET_MESSAGE_TYPE_ARM_RESULT, with an ID.
    */
   struct GNUNET_ARM_Message arm_msg;
 
   /**
-   * Result from the 'enum GNUNET_ARM_Result'
+   * Result from the `enum GNUNET_ARM_Result`
    */
   uint32_t result;
 };
@@ -106,7 +107,7 @@ struct GNUNET_ARM_ResultMessage
 struct GNUNET_ARM_ListResultMessage
 {
   /**
-   * Reply to client, of type is GNUNET_MESSAGE_TYPE_ARM_LIST_RESULT,
+   * Reply to client, of type is #GNUNET_MESSAGE_TYPE_ARM_LIST_RESULT,
    * with an ID.
    */
   struct GNUNET_ARM_Message arm_msg;
diff --git a/src/conversation/conversation_api.c b/src/conversation/conversation_api.c
index 9a02811fe..aad272d9c 100644
--- a/src/conversation/conversation_api.c
+++ b/src/conversation/conversation_api.c
@@ -117,7 +117,7 @@ struct GNUNET_CONVERSATION_Caller
   struct GNUNET_NAMESTORE_QueueEntry *qe;
 
   /**
-   * Identity of the person calling us (valid while in state #PS_RINGING).
+   * Identity of the person calling us.
    */
   struct GNUNET_CRYPTO_EcdsaPublicKey caller_id;
 
@@ -806,7 +806,7 @@ GNUNET_CONVERSATION_phone_destroy (struct GNUNET_CONVERSATION_Phone *phone)
  * and the microphone.  The call can later be resumed with
  * #GNUNET_CONVERSATION_caller_resume.
  *
- * @param phone phone to pause
+ * @param caller call to suspend
  */
 void
 GNUNET_CONVERSATION_caller_suspend (struct GNUNET_CONVERSATION_Caller *caller)
@@ -837,7 +837,7 @@ GNUNET_CONVERSATION_caller_suspend (struct GNUNET_CONVERSATION_Caller *caller)
 /**
  * Resume suspended conversation of a phone.
  *
- * @param phone phone to resume
+ * @param caller call to resume
  * @param speaker speaker to use
  * @param mic microphone to use
  */
diff --git a/src/conversation/conversation_api_call.c b/src/conversation/conversation_api_call.c
index efd6a60de..25e60f0f3 100644
--- a/src/conversation/conversation_api_call.c
+++ b/src/conversation/conversation_api_call.c
@@ -537,10 +537,10 @@ reconnect_call (struct GNUNET_CONVERSATION_Call *call)
  * @param caller_id identity of the caller
  * @param callee GNS name of the callee (used to locate the callee's record)
  * @param speaker speaker to use (will be used automatically immediately once the
- *        #GNUNET_CONVERSATION_EC_READY event is generated); we will NOT generate
+ *        #GNUNET_CONVERSATION_EC_CALL_PICKED_UP event is generated); we will NOT generate
  *        a ring tone on the speaker
  * @param mic microphone to use (will be used automatically immediately once the
- *        #GNUNET_CONVERSATION_EC_READY event is generated)
+ *        #GNUNET_CONVERSATION_EC_CALL_PICKED_UP event is generated)
  * @param event_handler how to notify the owner of the phone about events
  * @param event_handler_cls closure for @a event_handler
  */
@@ -595,8 +595,6 @@ finish_stop (void *cls)
  * Terminate a call.  The call may be ringing or ready at this time.
  *
  * @param call call to terminate
- * @param reason if the call was active (ringing or ready) this will be the
- *        reason given to the other user for why we hung up
  */
 void
 GNUNET_CONVERSATION_call_stop (struct GNUNET_CONVERSATION_Call *call)
@@ -674,14 +672,12 @@ GNUNET_CONVERSATION_call_suspend (struct GNUNET_CONVERSATION_Call *call)
 
 
 /**
- * Resumes a call after #GNUNET_CONVERSATION_call_pause.
+ * Resumes a call after #GNUNET_CONVERSATION_call_suspend.
  *
  * @param call call to resume
- * @param speaker speaker to use (will be used automatically immediately once the
- *        #GNUNET_CONVERSATION_EC_READY event is generated); we will NOT generate
+ * @param speaker speaker to use
  *        a ring tone on the speaker
- * @param mic microphone to use (will be used automatically immediately once the
- *        #GNUNET_CONVERSATION_EC_READY event is generated)
+ * @param mic microphone to use
  */
 void
 GNUNET_CONVERSATION_call_resume (struct GNUNET_CONVERSATION_Call *call,
diff --git a/src/include/gnunet_conversation_service.h b/src/include/gnunet_conversation_service.h
index b5a7fbc9a..cfe4a64ba 100644
--- a/src/include/gnunet_conversation_service.h
+++ b/src/include/gnunet_conversation_service.h
@@ -242,7 +242,7 @@ GNUNET_CONVERSATION_caller_pick_up (struct GNUNET_CONVERSATION_Caller *caller,
  * and the microphone.  The call can later be resumed with
  * #GNUNET_CONVERSATION_caller_resume.
  *
- * @param phone phone to pause
+ * @param caller call to suspend
  */
 void
 GNUNET_CONVERSATION_caller_suspend (struct GNUNET_CONVERSATION_Caller *caller);
@@ -251,7 +251,7 @@ GNUNET_CONVERSATION_caller_suspend (struct GNUNET_CONVERSATION_Caller *caller);
 /**
  * Resume suspended conversation of a phone.
  *
- * @param phone phone to resume
+ * @param caller call to resume
  * @param speaker speaker to use
  * @param mic microphone to use
  */
@@ -355,10 +355,10 @@ typedef void (*GNUNET_CONVERSATION_CallEventHandler)(void *cls,
  * @param caller_id identity of the caller
  * @param callee GNS name of the callee (used to locate the callee's record)
  * @param speaker speaker to use (will be used automatically immediately once the
- *        #GNUNET_CONVERSATION_EC_READY event is generated); we will NOT generate
+ *        #GNUNET_CONVERSATION_EC_CALL_PICKED_UP event is generated); we will NOT generate
  *        a ring tone on the speaker
  * @param mic microphone to use (will be used automatically immediately once the
- *        #GNUNET_CONVERSATION_EC_READY event is generated)
+ *        #GNUNET_CONVERSATION_EC_CALL_PICKED_UP event is generated)
  * @param event_handler how to notify the owner of the phone about events
  * @param event_handler_cls closure for @a event_handler
  */
@@ -383,14 +383,11 @@ GNUNET_CONVERSATION_call_suspend (struct GNUNET_CONVERSATION_Call *call);
 
 
 /**
- * Resumes a call after #GNUNET_CONVERSATION_call_pause.
+ * Resumes a call after #GNUNET_CONVERSATION_call_suspend.
  *
  * @param call call to resume
- * @param speaker speaker to use (will be used automatically immediately once the
- *        #GNUNET_CONVERSATION_EC_READY event is generated); we will NOT generate
- *        a ring tone on the speaker
- * @param mic microphone to use (will be used automatically immediately once the
- *        #GNUNET_CONVERSATION_EC_READY event is generated)
+ * @param speaker speaker to use
+ * @param mic microphone to use
  */
 void
 GNUNET_CONVERSATION_call_resume (struct GNUNET_CONVERSATION_Call *call,