From: Hermet Park <chuneon.park@samsung.com>
Date: Thu, 22 Jul 2021 04:10:30 +0000 (+0900)
Subject: doc: improved Saver documentation.
X-Git-Tag: accepted/tizen/unified/20210727.124506~10
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=7ad6a7ae5cd645aa132c0849b08fd25d9a4ec276;p=platform%2Fcore%2Fgraphics%2Ftizenvg.git

doc: improved Saver documentation.
---

diff --git a/inc/thorvg.h b/inc/thorvg.h
index 20ca52c..05aa3c0 100644
--- a/inc/thorvg.h
+++ b/inc/thorvg.h
@@ -1339,7 +1339,17 @@ public:
 /**
  * @class Saver
  *
- * @brief A class enabling saving a paint in a binary format.
+ * @brief A class for exporting a paint object into a specified file, from which to recover the paint data later.
+ *
+ * ThorVG provides a feature for exporting & importing paint data, the Saver has a role to export it to a file.
+ * Basically, this feature is useful when you need to save the composed scene or image from a paint object and recreate it later.
+ *
+ * The file format is decided by the extension name(i.e. "*.tvg") while the supported formats depend on the TVG packaging environment.
+ * If it doesn't support the file format, it will return the @c NonSuppport result by the save() method.
+ *
+ * Once you export a paint to the file successfully, you can recreate it using the Picture class.
+ *
+ * @see Picture::load()
  *
  * @BETA_API
  */
@@ -1349,21 +1359,46 @@ public:
     ~Saver();
 
     /**
-     * @brief Saves all the paints from the tree in a binary format.
+     * @brief Export the given @p paint data to the given @p path
      *
-     * @param[in] paint The root paint to be saved with all its nodes.
-     * @param[in] path A path to the file, in which the data is to be saved.
+     * @param[in] paint The paint to be saved with all its associated properties.
+     * @param[in] path A path to the file, in which the paint data is to be saved.
      *
      * @retval Result::Success When succeed.
-     * @retval Result::InvalidArguments the @p path is invalid.
-     * @retval Result::FailedAllocation An internal error with a memory allocation for the Saver object.
-     * @retval Result::MemoryCorruption When casting in the internal function implementation failed.
+     * @retval Result::NonSupport When trying to save a file with an unknown extension nor non supported format.
      * @retval Result::Unknown Others.
      *
+     * @note Saving can be asynchronous if the assigned thread number is greater than zero. To guarantee the saving is done, call sync() afterwards.
+     * @see Saver::sync()
+     *
+     * @BETA_API
      */
     Result save(std::unique_ptr<Paint> paint, const std::string& path) noexcept;
+
+    /**
+     * @brief Guarantees that the saving task is finished.
+     *
+     * The behavior of the saver will work on a sync/async basis, depending on the threading setting of the Initializer.
+     * Thus if you wish to have a benefit of it, you must call sync() after the save() in the proper delayed time.
+     * Otherwise, you can call sync() immediately.
+     *
+     * @return Result::Success when succeed.
+     * @return Result::InsufficientCondition otherwise.
+     *
+     * @note The asynchronous tasking is depend on the saver module implementation.
+     * @see Saver::save()
+     *
+     * @BETA_API
+     */
     Result sync() noexcept;
 
+    /**
+     * @brief Creates a new Saver object.
+     *
+     * @return A new Saver object.
+     *
+     * @BETA_API
+     */
     static std::unique_ptr<Saver> gen() noexcept;
 
     _TVG_DECLARE_PRIVATE(Saver);