TizenRefApp-9660 [Call Setting] Add doxygen documentation to UCL

util/*.h

Change-Id: Ifd8b7a4ed66870448c5ea8fa6fe301b21bf68c10

5 files changed, 159 insertions, 8 deletions

diff --git a/call-setting/common.h b/call-setting/common.h
index a4b1038..c64c61c 100644
--- a/call-setting/common.h
+++ b/call-setting/common.h
@@ -59,6 +59,7 @@ namespace call_setting {
 
 	namespace util {
 
+		using ucl::util::wrapUnique;
 		using ucl::util::makeUnique;
 		using ucl::util::dispose;
 	}
diff --git a/ucl/include/ucl/util/helpers.h b/ucl/include/ucl/util/helpers.h
index 5abf690..fe6b029 100644
--- a/ucl/include/ucl/util/helpers.h
+++ b/ucl/include/ucl/util/helpers.h
@@ -22,63 +22,146 @@
 
 namespace ucl {
 
+	/**
+	 * @brief Converts a value to corresponding Eina type
+	 * @param[in] value Original bool value
+	 * @return Corresponding Eina_Bool value
+	 */
 	constexpr Eina_Bool toEina(bool value);
 
-	// "nz()" - "Not Zero" functions
-	// return "zValue" if "!value" is true
+	/**
+	 * @brief Returns "zValue" if source is NULL
+	 * @param[in] value Source C-String
+	 * @param[in] zValue Value to return when "value" is NULL (optional: "")
+	 * @return "value" - if not NULL, "zValue" - otherwise
+	 */
 	constexpr const char *nz(const char *value, const char *zValue = "");
 
-	// "ne()" - "Not Empty" functions
-	// return "eValue" if "isEmpty(value)" is true
+	/**
+	 * @brief Returns "eValue" if source is empty string
+	 * @param[in] value Source C-String
+	 * @param[in] eValue Value to return when "value" is NULL (optional: NULL)
+	 * @return "value" - if not empty, "eValue" - otherwise
+	 */
 	constexpr const char *ne(const char *value, const char *eValue = nullptr);
 
+	/**
+	 * @brief Checks C-String for emptiness
+	 * @param[in] value Source C-String
+	 * @return true - if empty (NULL or ""), false - otherwise
+	 */
 	constexpr bool isEmpty(const char *value);
 
+	/**
+	 * @brief Checks T object for emptiness
+	 * @details Works by wrapping object's empty() method if exists
+	 * @param[in] value Source object
+	 * @return true - if empty, false - otherwise
+	 */
 	template <class T>
 	constexpr auto isEmpty(const T &value) -> decltype(value.empty())
 	{
 		return value.empty();
 	}
 
+	/**
+	 * @brief Checks T object for emptiness
+	 * @details Works by wrapping object's isEmpty() method if exists
+	 * @param[in] value Source object
+	 * @return true - if empty, false - otherwise
+	 */
 	template <class T>
 	constexpr auto isEmpty(const T &value) -> decltype(value.isEmpty())
 	{
 		return value.isEmpty();
 	}
 
+	/**
+	 * @brief Checks T object passed by pointer for emptiness
+	 * @details Uses isEmpty() function on dereferenced value if not NULL.
+	 * @param[in] value Source object pointer
+	 * @return true - if empty or NULL, false - otherwise
+	 */
 	template <class T>
 	constexpr auto isEmpty(const T &value) -> decltype(isEmpty(*value))
 	{
 		return (!value || isEmpty(*value));
 	}
 
+	/**
+	 * @brief Checks T object for validity
+	 * @details Works by wrapping object's valid() method if exists
+	 * @param[in] value Source object
+	 * @return true - if valid, false - otherwise
+	 */
 	template <class T>
 	constexpr auto isValid(const T &value) -> decltype(value.valid())
 	{
 		return value.valid();
 	}
 
+	/**
+	 * @brief Checks T object for validity
+	 * @details Works by wrapping object's isValid() method if exists
+	 * @param[in] value Source object
+	 * @return true - if valid, false - otherwise
+	 */
 	template <class T>
 	constexpr auto isValid(const T &value) -> decltype(value.isValid())
 	{
 		return value.isValid();
 	}
 
+	/**
+	 * @brief Checks T object passed by pointer for validity
+	 * @details Uses isValid() function on dereferenced value if not NULL.
+	 * @param[in] value Source object pointer
+	 * @return true - if valid, false - otherwise
+	 */
 	template <class T>
 	constexpr auto isValid(const T &value) -> decltype(isValid(*value))
 	{
 		return (value && isValid(*value));
 	}
 
+	/**
+	 * @brief Checks T object for not emptiness
+	 * @details Works by negating isEmpty() function
+	 * @param[in] value Source object
+	 * @return true - if not empty, false - otherwise
+	 */
 	template <class T>
 	constexpr bool isNotEmpty(T &&value);
 
+	/**
+	 * @brief Checks T object for not validity
+	 * @details Works by negating isValid() function
+	 * @param[in] value Source object
+	 * @return true - if not valid, false - otherwise
+	 */
 	template <class T>
 	constexpr bool isNotValid(T &&value);
 
+	/**
+	 * @brief Duplicates C-String with NULL check
+	 * @param[in] value Source C-String
+	 * @return Duplicated C-String or NULL
+	 */
 	char *strDupSafe(const char *value);
+
+	/**
+	 * @brief Compares C-String wrapped with nz() function
+	 * @param[in] lhs Left hand side C-String
+	 * @param[in] lhs Right hand side C-String
+	 * @return 0 - equals, <0 - less, >0 - greater
+	 */
 	int strCmpSafe(const char *lhs, const char *rhs);
 
+	/**
+	 * @brief Dynamically casts an object
+	 * @param[in] src Source object
+	 * @return Result object
+	 */
 	template <class T1, class T2>
 	inline auto dynamicCast(T2 &&src) -> decltype(
 			dynamic_cast<T1>(std::forward<T2>(src)))
@@ -86,6 +169,11 @@ namespace ucl {
 		return dynamic_cast<T1>(std::forward<T2>(src));
 	}
 
+	/**
+	 * @brief Const casts an object
+	 * @param[in] src Source object
+	 * @return Result object
+	 */
 	template <class T1, class T2>
 	inline auto constCast(T2 &&src) -> decltype(
 			const_cast<T1>(std::forward<T2>(src)))
@@ -93,21 +181,49 @@ namespace ucl {
 		return const_cast<T1>(std::forward<T2>(src));
 	}
 
+	/**
+	 * @brief Calculates minimum from two values
+	 * @param[in] a First value
+	 * @param[in] b Second value
+	 * @return Constant reference to minimum value
+	 */
 	template <class T>
 	constexpr const T &min(const T &a, const T &b);
 
+	/**
+	 * @brief Calculates maximum from two values
+	 * @param[in] a First value
+	 * @param[in] b Second value
+	 * @return Constant reference to maximum value
+	 */
 	template <class T>
 	constexpr const T &max(const T &a, const T &b);
 
+	/**
+	 * @brief Checks if a value is a Power of Two
+	 * @param[in] value Source value
+	 * @return true - if value is POT, false - otherwise
+	 */
 	template <class T>
 	constexpr bool isPot(T value)
 	{
 		return (((value - 1) & value) == 0);
 	}
 
+	/**
+	 * @brief Divides integer T by MULTIPLE with ceiling
+	 * @param[in] value Source value
+	 * @return Ceiled result of the division
+	 */
 	template <uint MULTIPLE, class T>
 	constexpr T ceilDiv(T value);
 
+	/**
+	 * @brief Rounds integer T to not less value that is a multiple of MULTIPLE
+	 * @details Optimized version for POT numbers
+	 * @param[in] value Source value
+	 * @return Result of the rounding
+	 */
 	template <uint MULTIPLE, class T>
 	constexpr typename std::enable_if<isPot(MULTIPLE), T>::type
 			roundUp(T value)
@@ -115,6 +231,12 @@ namespace ucl {
 		return ((value + (MULTIPLE - 1)) & ~static_cast<T>(MULTIPLE - 1));
 	}
 
+	/**
+	 * @brief Rounds integer T to not less value that is a multiple of MULTIPLE
+	 * @details Version for not POT numbers
+	 * @param[in] value Source value
+	 * @return Result of the rounding
+	 */
 	template <uint MULTIPLE, class T>
 	constexpr typename std::enable_if<!isPot(MULTIPLE), T>::type
 			roundUp(T value)
@@ -125,9 +247,26 @@ namespace ucl {
 
 namespace ucl { namespace util {
 
+	/**
+	 * @brief Wraps T object pointer with std::unique_ptr
+	 * @param[in] p Source pointer
+	 * @return Result std::unique_ptr
+	 */
 	template <class T>
-	std::unique_ptr<T> makeUnique(T *p);
+	std::unique_ptr<T> wrapUnique(T *p);
+
+	/**
+	 * @brief Makes new instance of T and calls wrapUnique()
+	 * @param[in] args Arguments for T constructor
+	 * @return Result std::unique_ptr
+	 */
+	template <class T, class ...ARGS>
+	std::unique_ptr<T> makeUnique(ARGS &&...args);
 
+	/**
+	 * @brief Safely disposes object and NULLs pointer
+	 * @param[in/out] p Target pointer
+	 */
 	template <class T, class = typename std::enable_if<
 			std::is_convertible<T *, IDisposable *>::value>::type>
 	inline void dispose(T *&p) noexcept
diff --git a/ucl/include/ucl/util/helpers.hpp b/ucl/include/ucl/util/helpers.hpp
index a7606f8..33fd326 100644
--- a/ucl/include/ucl/util/helpers.hpp
+++ b/ucl/include/ucl/util/helpers.hpp
@@ -80,8 +80,14 @@ namespace ucl {
 namespace ucl { namespace util {
 
 	template <class T>
-	inline std::unique_ptr<T> makeUnique(T *const p)
+	inline std::unique_ptr<T> wrapUnique(T *const p)
 	{
 		return std::unique_ptr<T>(p);
 	}
+
+	template <class T, class ...ARGS>
+	inline std::unique_ptr<T> makeUnique(ARGS &&...args)
+	{
+		return wrapUnique(new T(std::forward<ARGS>(args)...));
+	}
 }}
diff --git a/ucl/include/ucl/util/logging.h b/ucl/include/ucl/util/logging.h
index 804a513..da3e115 100644
--- a/ucl/include/ucl/util/logging.h
+++ b/ucl/include/ucl/util/logging.h
@@ -23,6 +23,11 @@
 
 #include "types/Result.h"
 
+/**
+ * @brief Gets result data for result codes defined in "ucl/types/Result.h"
+ * @param[in] result Result value
+ * @return Corresponding result data for the result value
+ */
 ::ucl::ResultData getUCLResultData(::ucl::Result result);
 
 #ifndef UCL_LOG_LEVEL
diff --git a/ucl/source/appfw/UIApp.cpp b/ucl/source/appfw/UIApp.cpp
index bb44971..debb5ac 100644
--- a/ucl/source/appfw/UIApp.cpp
+++ b/ucl/source/appfw/UIApp.cpp
@@ -173,9 +173,9 @@ namespace ucl {
 	void UIApp::initSysEventManager()
 	{
 		m_instanceMgr.setSysEventProvider(
-				util::makeUnique(new SysEventProvider(
+				util::makeUnique<SysEventProvider>(
 					&ui_app_add_event_handler,
-					&ui_app_remove_event_handler)));
+					&ui_app_remove_event_handler));
 	}
 
 	Result UIApp::createInstance()