Update API header for review

Change-Id: Id6467576ebc30f538d8e6a45d1fdee80169aa9d7

diff --git a/include/multi_assistant.h b/include/multi_assistant.h
index afe85872b404de7501ab1c0f3bab039cbaa60b18..6f6d8941fec6355113a81e5b874fdd8de8c35ef0 100644 (file)
--- a/include/multi_assistant.h
+++ b/include/multi_assistant.h
@@ -118,8 +118,8 @@ int ma_unprepare(void);
  * @retval #MA_ERROR_NONE Successful
  * @retval #MA_ERROR_NOT_SUPPORTED Not supported
  * @retval #MA_ERROR_PERMISSION_DENIED Permission denied
- * @retval #MA_ERROR_INVALID_STATE Invalid state
  * @retval #MA_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #MA_ERROR_INVALID_STATE Invalid state
  */
 int ma_get_state(ma_state_e* state);
 
@@ -154,8 +154,8 @@ int ma_get_current_language(char** language);
  * @retval #MA_ERROR_NONE Successful
  * @retval #MA_ERROR_NOT_SUPPORTED Not supported
  * @retval #MA_ERROR_PERMISSION_DENIED Permission denied
- * @retval #MA_ERROR_INVALID_STATE Invalid state
  * @retval #MA_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #MA_ERROR_INVALID_STATE Invalid state
  * @retval #MA_ERROR_OPERATION_FAILED Operation failed
  *
  * @pre The state should be #MA_STATE_READY.
@@ -172,8 +172,8 @@ int ma_get_recording_audio_format(int* rate, ma_audio_channel_e* channel, ma_aud
  * @return @c 0 on success, otherwise a negative error value
  * @retval #MA_ERROR_NONE Successful
  * @retval #MA_ERROR_NOT_SUPPORTED Not supported
- * @retval #MA_ERROR_INVALID_STATE Invalid state
  * @retval #MA_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #MA_ERROR_INVALID_STATE Invalid state
  *
  * @pre The state should be #MA_STATE_INITIALIZED.
  * @see ma_state_changed_cb()
@@ -206,8 +206,8 @@ int ma_unset_state_changed_cb(void);
  * @return @c 0 on success, otherwise a negative error value
  * @retval #MA_ERROR_NONE Successful
  * @retval #MA_ERROR_NOT_SUPPORTED Not supported
- * @retval #MA_ERROR_INVALID_STATE Invalid state
  * @retval #MA_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #MA_ERROR_INVALID_STATE Invalid state
  *
  * @pre The state should be #MA_STATE_INITIALIZED.
  * @see ma_error_cb()
@@ -240,8 +240,8 @@ int ma_unset_error_cb(void);
  * @return @c 0 on success, otherwise a negative error value
  * @retval #MA_ERROR_NONE Successful
  * @retval #MA_ERROR_NOT_SUPPORTED Not supported
- * @retval #MA_ERROR_INVALID_STATE Invalid state
  * @retval #MA_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #MA_ERROR_INVALID_STATE Invalid state
  *
  * @pre The state should be #MA_STATE_INITIALIZED.
  * @see ma_language_changed_cb()
@@ -274,8 +274,8 @@ int ma_unset_language_changed_cb(void);
  * @return @c 0 on success, otherwise a negative error value
  * @retval #MA_ERROR_NONE Successful
  * @retval #MA_ERROR_NOT_SUPPORTED Not supported
- * @retval #MA_ERROR_INVALID_STATE Invalid state
  * @retval #MA_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #MA_ERROR_INVALID_STATE Invalid state
  *
  * @pre The state should be #MA_STATE_INITIALIZED.
  * @see ma_audio_streaming_cb()
@@ -359,8 +359,8 @@ int ma_send_recognition_result(ma_recognition_result_event_e result);
  * @return @c 0 on success, otherwise a negative error value
  * @retval #MA_ERROR_NONE Successful
  * @retval #MA_ERROR_NOT_SUPPORTED Not supported
- * @retval #MA_ERROR_INVALID_STATE Invalid state
  * @retval #MA_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #MA_ERROR_INVALID_STATE Invalid state
  *
  * @pre The state should be #MA_STATE_INITIALIZED.
  * @see ma_active_state_changed_cb()
@@ -457,8 +457,8 @@ int ma_send_assistant_specific_command(const char* command);
  * @return @c 0 on success, otherwise a negative error value
  * @retval #MA_ERROR_NONE Successful
  * @retval #MA_ERROR_NOT_SUPPORTED Not supported
- * @retval #MA_ERROR_INVALID_STATE Invalid state
  * @retval #MA_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #MA_ERROR_INVALID_STATE Invalid state
  *
  * @pre The state should be #MA_STATE_INITIALIZED.
  * @see ma_wakeup_engine_command_cb()
@@ -482,7 +482,7 @@ int ma_set_wakeup_engine_command_cb(ma_wakeup_engine_command_cb callback, void*
 int ma_unset_wakeup_engine_command_cb(void);
 
 /**
- * @brief Retrieves all installed voice assistant applications information.
+ * @brief Retrieves the information about all installed voice assistant applications.
  * @since_tizen 5.5
  *
  * @param[in] callback A callback for getting the information of the installed assistants.
@@ -491,20 +491,20 @@ int ma_unset_wakeup_engine_command_cb(void);
  * @return @c 0 on success, otherwise a negative error value
  * @retval #MA_ERROR_NONE Successful
  * @retval #MA_ERROR_NOT_SUPPORTED Not supported
- * @retval #MA_ERROR_INVALID_STATE Invalid state
  * @retval #MA_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #MA_ERROR_INVALID_STATE Invalid state
  *
  * @see ma_voice_assistant_list_cb()
  */
 int ma_assistant_info_foreach_assistants(ma_assistant_info_list_cb callback, void* user_data);
 
 /**
- * @brief Gets the app id of the specific handle.
+ * @brief Gets the app id of the specified handle.
  * @since_tizen 5.5
  *
  * @remarks You must not release @a app_id using free().
  * @param[in] handle The handle to the assistant's information
- * @param[in] app_id The application ID of the given assistant handle
+ * @param[out] app_id The application ID of the given assistant handle
  *
  * @return @c 0 on success, otherwise a negative error value
  * @retval #MA_ERROR_NONE Successful
@@ -514,7 +514,7 @@ int ma_assistant_info_foreach_assistants(ma_assistant_info_list_cb callback, voi
 int ma_assistant_info_get_app_id(ma_assistant_info_h handle, char** app_id);
 
 /**
- * @brief Gets the enabled status of the specific handle.
+ * @brief Gets the enabled status of the specified handle.
  * @since_tizen 5.5
  *
  * @param[in] handle The handle to the assistant's information
@@ -528,21 +528,7 @@ int ma_assistant_info_get_app_id(ma_assistant_info_h handle, char** app_id);
 int ma_assistant_info_get_enabled_status(ma_assistant_info_h handle, bool* status);
 
 /**
- * @brief Gets the name of the specific handle.
- * @since_tizen 5.5
- *
- * @param[in] handle The handle to the assistant's information
- * @param[in] name The application name of the given assistant handle
- *
- * @return @c 0 on success, otherwise a negative error value
- * @retval #MA_ERROR_NONE Successful
- * @retval #MA_ERROR_NOT_SUPPORTED Not supported
- * @retval #MA_ERROR_INVALID_PARAMETER Invalid parameter
- */
-int ma_assistant_info_get_name(ma_assistant_info_h handle, char** name);
-
-/**
- * @brief Gets the type information of recording audio source.
+ * @brief Gets the recording audio source type.
  * @since_tizen 5.5
  * @privlevel public
  * @privilege %http://tizen.org/privilege/recorder
@@ -554,8 +540,8 @@ int ma_assistant_info_get_name(ma_assistant_info_h handle, char** name);
  * @retval #MA_ERROR_NONE Successful
  * @retval #MA_ERROR_NOT_SUPPORTED Not supported
  * @retval #MA_ERROR_PERMISSION_DENIED Permission denied
- * @retval #MA_ERROR_INVALID_STATE Invalid state
  * @retval #MA_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #MA_ERROR_INVALID_STATE Invalid state
  * @retval #MA_ERROR_OPERATION_FAILED Operation failed
  *
  * @pre The state should be #MA_STATE_READY.
@@ -568,15 +554,15 @@ int ma_get_recording_audio_source_type(char** type);
  * @privlevel public
  * @privilege %http://tizen.org/privilege/recorder
  *
- * @remarks The @a ratio must be in 0.0~1.0 .
+ * @remarks The @a ratio must be a value between 0.0 and 1.0 (inclusive).
  * @param[in] ratio The volume ratio to be set
  *
  * @return @c 0 on success, otherwise a negative error value
  * @retval #MA_ERROR_NONE Successful
  * @retval #MA_ERROR_NOT_SUPPORTED Not supported
  * @retval #MA_ERROR_PERMISSION_DENIED Permission denied
- * @retval #MA_ERROR_INVALID_STATE Invalid state
  * @retval #MA_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #MA_ERROR_INVALID_STATE Invalid state
  * @retval #MA_ERROR_OPERATION_FAILED Operation failed
  *
  * @pre The state should be #MA_STATE_READY.
@@ -614,8 +600,8 @@ int ma_set_preprocessing_allow_mode(ma_preprocessing_allow_mode_e mode, const ch
  * @return @c 0 on success, otherwise a negative error value
  * @retval #MA_ERROR_NONE Successful
  * @retval #MA_ERROR_NOT_SUPPORTED Not supported
- * @retval #MA_ERROR_INVALID_STATE Invalid state
  * @retval #MA_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #MA_ERROR_INVALID_STATE Invalid state
  *
  * @pre The state should be #MA_STATE_INITIALIZED.
  * @see ma_preprocessing_information_changed_cb()

diff --git a/include/multi_assistant_common.h b/include/multi_assistant_common.h
index a80e3196c7de3885ad62e15a53a2a65d1bcd1f42..caa7553b80212c6e9d8100bebff7cd7e1faeb746 100644 (file)
--- a/include/multi_assistant_common.h
+++ b/include/multi_assistant_common.h
@@ -237,7 +237,8 @@ typedef void (*ma_active_state_changed_cb)(ma_active_state_e previous, ma_active
 typedef void (*ma_wakeup_engine_command_cb)(const char *command, void* user_data);
 
 /**
- * @brief A handle to get assistant information
+ * @brief A handle to get assistant information.
+ * @since_tizen 5.5
  */
 
 typedef void *ma_assistant_info_h;
@@ -246,6 +247,8 @@ typedef void *ma_assistant_info_h;
  * @brief Called to get the assistant information once for each installed assistant.
  * @since_tizen 5.5
  *
+ * @remarks The @a handle should not be released.
+ * @remarks The @a handle is managed by the platform and will be released when application exits.
  * @param[in] handle The handle of the assistant
  * @param[in] user_data The user data passed from the callback registration function
  */
@@ -258,6 +261,7 @@ typedef int (*ma_assistant_info_list_cb)(ma_assistant_info_h handle, void* user_
  * @remarks The @a app_id should not be released and can be used only in the callback. To use outside, make a copy.
  * @remarks If the @a app_id is NULL, it means there is no preprocessing voice assistant available.
  * @param[in] app_id The application id of current preprocessing voice assistant
+ * @param[in] user_data The user data passed from the callback registration function
  */
 typedef void (*ma_preprocessing_information_changed_cb)(const char* app_id, void* user_data);