Revise header

Remove '\n' command from related sentence.
Add more references.
Add more @remarks and @post.
Some sentences are rephrased.

[Version] 0.2.62
[Issue Type] Doxygen

Change-Id: I4b90e3baab26ab21cd047d874e87b1c0ac152274
Signed-off-by: Sangchul Lee <sc11.lee@samsung.com>

diff --git a/doc/webrtc_doc.h b/doc/webrtc_doc.h
index 438a9152e9b05cd167a87126f096da6579b26e93..3d2d28e307fbacb9a049deac775bc285d9872d44 100644 (file)
--- a/doc/webrtc_doc.h
+++ b/doc/webrtc_doc.h
@@ -27,7 +27,7 @@
 /**
  * @ingroup CAPI_MEDIA_FRAMEWORK
  * @defgroup CAPI_MEDIA_WEBRTC_MODULE WebRTC
- * @brief The @ref CAPI_MEDIA_WEBRTC_MODULE API provides functions for real-time communication between peers.
+ * @brief The @ref CAPI_MEDIA_WEBRTC_MODULE API provides functions for real-time audio/video communication between peers. It supports WebRTC as a native API based on GStreamer multimedia framework.
  *
  * @section CAPI_MEDIA_WEBRTC_MODULE_HEADER Required Header
  *   \#include <webrtc.h>
@@ -42,7 +42,7 @@
  *  - start/stop the state of the handle
  *  - make negotiation with the remote peer
  *  - query the various states of the handle including session negotiation
- *  - get notified various states changes via callbacks
+ *  - get notified about various changes via callbacks
  *
  * @subsection CAPI_MEDIA_WEBRTC_LIFE_CYCLE_STATE_TRANSITIONS State Transitions
  * <div><table class="doxtable" >
@@ -181,7 +181,7 @@
 /**
  * @ingroup CAPI_MEDIA_WEBRTC_MODULE
  * @defgroup CAPI_MEDIA_WEBRTC_MEDIA_SOURCE_MODULE Media Source
- * @brief The @ref CAPI_MEDIA_WEBRTC_MEDIA_SOURCE_MODULE API provides functions to manage media sources to send to the remote peer.
+ * @brief The @ref CAPI_MEDIA_WEBRTC_MEDIA_SOURCE_MODULE API provides functions to manage media sources to communicate with the remote peer.
  * @section CAPI_MEDIA_WEBRTC_MEDIA_SOURCE_MODULE_HEADER Required Header
  *    \#include <webrtc.h>
  *

diff --git a/include/webrtc.h b/include/webrtc.h
index ca025c1bd68c1f2ac4bf6958f61faae36dbb6d76..ddb64e0579303a6b4ab7ce0a7acfcaad186c056c 100644 (file)
--- a/include/webrtc.h
+++ b/include/webrtc.h
@@ -62,6 +62,7 @@ typedef enum {
 
 /**
  * @brief Enumeration for WebRTC state.
+ * @details See \ref CAPI_MEDIA_WEBRTC_LIFE_CYCLE_STATE_TRANSITIONS.
  * @since_tizen 6.5
  */
 typedef enum {
@@ -73,6 +74,7 @@ typedef enum {
 /**
  * @brief Enumeration for WebRTC peer connection state.
  * @since_tizen 6.5
+ * @remarks It corresponds with the RTCPeerConnectionState enum described in https://www.w3.org/TR/webrtc/#rtcpeerconnectionstate-enum.
  */
 typedef enum {
        WEBRTC_PEER_CONNECTION_STATE_NEW,          /**<  New */
@@ -86,6 +88,7 @@ typedef enum {
 /**
  * @brief Enumeration for WebRTC signaling state.
  * @since_tizen 6.5
+ * @remarks It corresponds with the RTCSignalingState enum described in https://www.w3.org/TR/webrtc/#rtcsignalingstate-enum.
  */
 typedef enum {
        WEBRTC_SIGNALING_STATE_STABLE,               /**<  Stable */
@@ -99,6 +102,7 @@ typedef enum {
 /**
  * @brief Enumeration for WebRTC ICE gathering state.
  * @since_tizen 6.5
+ * @remarks It corresponds with the RTCIceGatheringState enum described in https://www.w3.org/TR/webrtc/#rtcicegatheringstate-enum.
  */
 typedef enum {
        WEBRTC_ICE_GATHERING_STATE_NEW,        /**<  New */
@@ -109,6 +113,7 @@ typedef enum {
 /**
  * @brief Enumeration for WebRTC ICE connection state.
  * @since_tizen 6.5
+ * @remarks It corresponds with the RTCIceConnectionState enum described in https://www.w3.org/TR/webrtc/#rtciceconnectionstate-enum.
  */
 typedef enum {
        WEBRTC_ICE_CONNECTION_STATE_NEW,           /**<  New */
@@ -123,6 +128,7 @@ typedef enum {
 /**
  * @brief Enumeration for WebRTC ICE transport policy.
  * @since_tizen 6.5
+ * @remarks It corresponds with the RTCIceTransportPolicy enum described in https://www.w3.org/TR/webrtc/#rtcicetransportpolicy-enum.
  */
 typedef enum {
        WEBRTC_ICE_TRANSPORT_POLICY_ALL,           /**<  All */
@@ -192,6 +198,10 @@ typedef enum {
 /**
  * @brief WebRTC display handle type.
  * @since_tizen 6.5
+ * @remarks The pointer of this handle can be obtained from EFL UI API.\n
+ *          For example, in case of #WEBRTC_DISPLAY_TYPE_OVERLAY, elm_win_add() can be used to get the window handle.\n
+ *          In case of #WEBRTC_DISPLAY_TYPE_EVAS, evas_object_image_add() can be used to get the renderable image handle.\n
+ *          For more details, please refer to https://docs.tizen.org/application/native/guides/ui/efl/.
  */
 typedef void *webrtc_display_h;
 
@@ -360,6 +370,7 @@ typedef void (*webrtc_negotiation_needed_cb)(webrtc_h webrtc, void *user_data);
  * @param[in] webrtc     WebRTC handle
  * @param[in] candidate  The ICE candidate message
  * @param[in] user_data  The user data passed from the callback registration function
+ * @post @a candidate must be sent to the remote peer via the signaling channel.
  * @see webrtc_set_ice_candidate_cb()
  * @see webrtc_unset_ice_candidate_cb()
  */
@@ -477,7 +488,7 @@ typedef void (*webrtc_data_channel_open_cb)(webrtc_data_channel_h channel, void
  * @remarks The @a channel is the same object for which the callback was set.\n
  *          The @a channel should not be released.\n
  *          When @a type is #WEBRTC_DATA_CHANNEL_TYPE_STRING, @a message should be casted to char pointer.\n
- *          When @a type is #WEBRTC_DATA_CHANNEL_TYPE_BYTES, @a message should be casted to #webrtc_bytes_data_h.\n
+ *          When @a type is #WEBRTC_DATA_CHANNEL_TYPE_BYTES, @a message should be casted to #webrtc_bytes_data_h.
  *          In this case, webrtc_get_data() can be used to get the data and its size inside of this callback.\n
  *          The @a message should not be released.
  * @param[in] channel    WebRTC data channel handle
@@ -568,7 +579,8 @@ int webrtc_unset_error_cb(webrtc_h webrtc);
  * @since_tizen 6.5
  * @privlevel public
  * @privilege %http://tizen.org/privilege/internet
- * @remarks The @a webrtc should be released using webrtc_destroy().
+ * @remarks A signaling channel not addressed in this API should be established to send SDP or ICE candidate messages to each other.\n
+ *          The @a webrtc should be released using webrtc_destroy().
  * @param[out] webrtc    WebRTC handle
  * @return @c 0 on success,
  *         otherwise a negative error value
@@ -793,7 +805,7 @@ int webrtc_media_source_get_transceiver_direction(webrtc_h webrtc, unsigned int
 int webrtc_media_source_set_pause(webrtc_h webrtc, unsigned int source_id, webrtc_media_type_e media_type, bool pause);
 
 /**
- * @brief Gets the pause of the media source.
+ * @brief Gets the pause state of the media source.
  * @since_tizen 6.5
  * @remarks The default value is @c false.
  * @param[in] webrtc      WebRTC handle
@@ -829,7 +841,7 @@ int webrtc_media_source_get_pause(webrtc_h webrtc, unsigned int source_id, webrt
 int webrtc_media_source_set_mute(webrtc_h webrtc, unsigned int source_id, webrtc_media_type_e media_type, bool mute);
 
  /**
- * @brief Gets the mute of the media source.
+ * @brief Gets the mute state of the media source.
  * @details If @a source_id is a media source of #WEBRTC_MEDIA_SOURCE_TYPE_FILE or #WEBRTC_MEDIA_SOURCE_TYPE_MEDIA_PACKET,
             this function will return #WEBRTC_ERROR_INVALID_PARAMETER.
  * @since_tizen 6.5
@@ -849,7 +861,7 @@ int webrtc_media_source_get_mute(webrtc_h webrtc, unsigned int source_id, webrtc
 
 /**
  * @brief Sets a video resolution to the media source.
- * @details The following media source types are for the video:\n
+ * @details The following media source types contain video:\n
  *          #WEBRTC_MEDIA_SOURCE_TYPE_VIDEOTEST\n
  *          #WEBRTC_MEDIA_SOURCE_TYPE_CAMERA\n
  *          #WEBRTC_MEDIA_SOURCE_TYPE_SCREEN
@@ -872,7 +884,7 @@ int webrtc_media_source_set_video_resolution(webrtc_h webrtc, unsigned int sourc
 
 /**
  * @brief Gets the video resolution of the media source.
- * @details The following media source types are for the video:\n
+ * @details The following media source types contain video:\n
  *          #WEBRTC_MEDIA_SOURCE_TYPE_VIDEOTEST\n
  *          #WEBRTC_MEDIA_SOURCE_TYPE_CAMERA\n
  *          #WEBRTC_MEDIA_SOURCE_TYPE_SCREEN
@@ -1207,6 +1219,7 @@ int webrtc_media_source_set_video_loopback(webrtc_h webrtc, unsigned source_id,
 /**
  * @brief Sets a STUN server URL.
  * @since_tizen 6.5
+ * @remarks Regarding STUN, refer to the RFC7064(https://tools.ietf.org/html/rfc7064).
  * @param[in] webrtc       WebRTC handle
  * @param[in] stun_server  The STUN server URL
  * @return @c 0 on success,
@@ -1234,8 +1247,9 @@ int webrtc_get_stun_server(webrtc_h webrtc, char **stun_server);
 /**
  * @brief Adds a TURN server URL.
  * @since_tizen 6.5
+ * @remarks Regarding TURN, refer to the RFC7065(https://tools.ietf.org/html/rfc7065).
  * @param[in] webrtc       WebRTC handle
- * @param[in] turn_server  The TURN server URL of the form turn(s)://username:password@host:port
+ * @param[in] turn_server  The TURN server URL of the form turn(s)://username:password\@host:port
  * @return @c 0 on success,
  *         otherwise a negative error value
  * @retval #WEBRTC_ERROR_NONE    Successful
@@ -1264,7 +1278,6 @@ int webrtc_foreach_turn_server(webrtc_h webrtc, webrtc_turn_server_cb callback,
 /**
  * @brief Sets a ICE transport policy that represents which candidates the ICE Agent is allowed to use.
  * @since_tizen 6.5
- * @remarks The @a policy enum corresponds with the RTCIceTransportPolicy enum described in https://www.w3.org/TR/webrtc/#rtcicetransportpolicy-enum.\n
  * @param[in] webrtc       WebRTC handle
  * @param[in] policy       The ICE transport policy
  * @return @c 0 on success,
@@ -1280,8 +1293,7 @@ int webrtc_set_ice_transport_policy(webrtc_h webrtc, webrtc_ice_transport_policy
 /**
  * @brief Gets the ICE transport policy.
  * @since_tizen 6.5
- * @remarks The @a policy enum corresponds with the RTCIceTransportPolicy enum described in https://www.w3.org/TR/webrtc/#rtcicetransportpolicy-enum.\n
- *          The default value is #WEBRTC_ICE_TRANSPORT_POLICY_ALL.
+ * @remarks The default value is #WEBRTC_ICE_TRANSPORT_POLICY_ALL.
  * @param[in] webrtc       WebRTC handle
  * @param[out] policy      The ICE transport policy
  * @return @c 0 on success,
@@ -1566,6 +1578,8 @@ int webrtc_unset_ice_candidate_cb(webrtc_h webrtc);
  * @retval #WEBRTC_ERROR_INVALID_OPERATION Invalid operation
  * @retval #WEBRTC_ERROR_INVALID_STATE Invalid state
  * @pre @a webrtc state must be set to #WEBRTC_STATE_NEGOTIATING.
+ * @post @a offer must be set as a local description by calling webrtc_set_local_description()
+ * @post @a offer must be sent to the remote peer via the signaling channel.
  * @see webrtc_state_changed_cb()
  * @see webrtc_negotiation_needed_cb()
  * @see webrtc_set_local_description()
@@ -1589,6 +1603,8 @@ int webrtc_create_offer(webrtc_h webrtc, bundle *options, char **offer);
  * @pre @a webrtc state must be set to #WEBRTC_STATE_NEGOTIATING.
  * @pre The remote SDP offer must be set by calling webrtc_set_remote_description().
  * @pre The signaling state must be set to #WEBRTC_SIGNALING_STATE_HAVE_REMOTE_OFFER.
+ * @post @a answer must be set as a local description by calling webrtc_set_local_description()
+ * @post @a answer must be sent to the remote peer via the signaling channel.
  * @see webrtc_set_remote_description()
  * @see webrtc_set_local_description()
  * @see webrtc_get_signaling_state()

diff --git a/packaging/capi-media-webrtc.spec b/packaging/capi-media-webrtc.spec
index 1af033e82295af5b0c96a11c2417cf42a56e735f..ceea00e81f902cc80882a5f188bfbf6e8e982af7 100644 (file)
--- a/packaging/capi-media-webrtc.spec
+++ b/packaging/capi-media-webrtc.spec
@@ -1,6 +1,6 @@
 Name:       capi-media-webrtc
 Summary:    A WebRTC library in Tizen Native API
-Version:    0.2.61
+Version:    0.2.62
 Release:    0
 Group:      Multimedia/API
 License:    Apache-2.0