Modified explanation of new apis

Change-Id: Ie44061c7254dcd3d6f16cc7a386e48de9f4c5270

diff --git a/include/media_format.h b/include/media_format.h
index 992884158fa3daa40df7b5c125c5677e205929f3..dd66aba584bf4c7fa38fa92c4f49f3bb0d01a552 100755 (executable)
--- a/include/media_format.h
+++ b/include/media_format.h
@@ -683,13 +683,15 @@ int media_format_is_writable(media_format_h fmt, bool * is_writable);
 
  /**
  * @brief Returns a writable copy of media_format_h.
- * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @details If there is only one reference count on fmt, the caller must be the owner,
  *              and so this function will return the object unchanged.
  *              while, if there is more than one reference count on the object, a new object will be returned.
  *              The caller will own a reference to the returned object.
  *              In a nutshell, this function unrefs the fmt and refs the out_fmt returned.
  *              Don't access fmt after calling this function.
+ * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
+ * @remarks If a new object is returned, it will not have its own copy of extra data.
+ *          The new object's extra data object will be the original object's extra data.
  * @param[in] fmt exist media_format_h , don't access it after calling this function
  * @param[out] out_fmt new copied media_format_h, the caller is owner of this object
  *
@@ -704,10 +706,13 @@ int media_format_make_writable(media_format_h fmt, media_format_h * out_fmt);
 
 /**
  * @brief Sets extra data of media format.
- * @details    The user can sets data that media format does not support.
+ * @details    The user can set data that media format does not support.
  * @since_tizen 4.0
+ * @remarks The application is responsible for freeing @a extra_data.
+ *          For description of extra data behavior upon making an object writable,
+ *          see the description of media_format_make_writable().
  * @param[in] fmt   The media format handle
- * @param[in] extra    The extra data to set
+ * @param[in] extra_data  The extra data to set
  *
  * @return @c 0 on success,
  *         otherwise a negative error value
@@ -715,14 +720,17 @@ int media_format_make_writable(media_format_h fmt, media_format_h * out_fmt);
  * @retval #MEDIA_FORMAT_ERROR_INVALID_PARAMETER Invalid parameter
  * @see media_format_get_extra()
  */
-int media_format_set_extra(media_format_h fmt, void *extra);
+int media_format_set_extra(media_format_h fmt, void *extra_data);
 
 /**
  * @brief Gets extra data of media format.
  * @details    The user can get extra data which user sets value via media_format_set_extra().
  * @since_tizen 4.0
+ * @remarks The application is responsible for freeing @a extra_data.
+ *          For description of extra data behavior upon making an object writable,
+ *          see the description of media_format_make_writable().
  * @param[in]  fmt   The media format handle
- * @param[out] extra    The extra data to get
+ * @param[out] extra_data    The extra data to get
  *
  * @return @c 0 on success,
  *         otherwise a negative error value
@@ -730,7 +738,7 @@ int media_format_set_extra(media_format_h fmt, void *extra);
  * @retval #MEDIA_FORMAT_ERROR_INVALID_PARAMETER Invalid parameter
  * @see media_format_set_extra()
  */
-int media_format_get_extra(media_format_h fmt, void **extra);
+int media_format_get_extra(media_format_h fmt, void **extra_data);
 /**
  * @}
  */