From: Sejun Park <sejun79.park@samsung.com>
Date: Tue, 25 Apr 2017 09:37:34 +0000 (+0900)
Subject: Modified explanation of new apis
X-Git-Tag: submit/tizen/20170426.083740^0
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=80eb0b3ecfc1b4376a1a9375dfffe28d0cb922b2;p=platform%2Fcore%2Fapi%2Fmediatool.git

Modified explanation of new apis

Change-Id: Ie44061c7254dcd3d6f16cc7a386e48de9f4c5270
---

diff --git a/include/media_format.h b/include/media_format.h
index 9928841..dd66aba 100755
--- 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);
 /**
  * @}
  */