Review/modify/add the API doc (utils folder) (#1182)

In `olp-cpp-sdk-core/include/Utils`, review and modify the existing
documentation and add missing descriptions so that we have fewer errors
when building the API ref.

Relates-To: OLPEDGE-1450
Signed-off-by: Halyna Dumych <[email protected]>

Author: HalynaDumych

olp-cpp-sdk-core/include/olp/core/utils/Base64.h

@@ -30,42 +30,42 @@ namespace olp {
 namespace utils {
 
 /**
- * @brief Encodes binary stream into base64 text.
+ * @brief Encodes a binary stream into a Base64 text.
  *
- * @param bytes Data to be encoded.
+ * @param bytes The data to be encoded.
  *
- * @return Base64 encoded string.
+ * @return The Base64 encoded string.
  */
 CORE_API std::string Base64Encode(const std::vector<std::uint8_t>& bytes);
 
 /**
- * @brief Encodes binary stream into base64 text.
+ * @brief Encodes a string into a Base64 text.
  *
- * @param bytes Data to be encoded.
+ * @param bytes The data to be encoded.
  *
- * @return Base64 encoded string.
+ * @return The Base64 encoded string.
  */
 CORE_API std::string Base64Encode(const std::string& bytes);
 
 /**
- * @brief Encodes binary stream into base64 text.
+ * @brief Encodes a binary stream into a Base64 text.
  *
- * @param bytes Data to be encoded.
- * @param size The length of the bytes array.
+ * @param bytes The data to be encoded.
+ * @param size The length of the byte array.
  *
- * @return Base64 encoded string.
+ * @return The Base64 encoded string.
  */
 CORE_API std::string Base64Encode(const void* bytes, size_t size);
 
 /**
- * @brief Decodes base64 into a binary stream.
+ * @brief Decodes a Base64 string into a binary stream.
  *
- * @param[in] string Base64 string to be decoded.
- * @param[out] bytes Vector containing decoded bytes.
- * @param[in] write_null_bytes True if decoded null bytes should be written to
- * the output, false otherwise. Default is true.
+ * @param[in] string The Base64 string to be decoded.
+ * @param[out] bytes The vector containing the decoded bytes.
+ * @param[in] write_null_bytes True if the decoded NULL bytes should be written to
+ * the output; false otherwise. The default value is true.
  *
- * @return \c true if decoding was successful, \c false otherwise.
+ * @return True if the decoding was successful; false otherwise.
  */
 CORE_API bool Base64Decode(const std::string& string,
                            std::vector<std::uint8_t>& bytes,

olp-cpp-sdk-core/include/olp/core/utils/Config.h

@@ -20,23 +20,19 @@
 #pragma once
 
 /**
- * @file
- * Contains macros to determine the compile-time configuration.
+ * @file Config.h
+ * @brief Contains macros that determine the compile-time configuration.
  */
 
-/**
- * Defined to 1 if exceptions are enabled, 0 if disabled.
- */
+/// Set to 1 if the exceptions are enabled; 0 if disabled.
 #define CORE_EXCEPTIONS_ENABLED 0
 
 #if defined(__EXCEPTIONS) || defined(_CPPUNWIND) || defined(__CPPUNWIND)
 #undef CORE_EXCEPTIONS_ENABLED
 #define CORE_EXCEPTIONS_ENABLED 1
 #endif
 
-/**
- * Defined to 1 if C++ RTTI is enabled, 0 if disabled.
- */
+/// Set to 1 if C++ RTTI is enabled; 0 if disabled.
 #define CORE_RTTI_ENABLED 0
 
 #if defined(__GNUC__)

olp-cpp-sdk-core/include/olp/core/utils/Dir.h

@@ -27,97 +27,101 @@
 namespace olp {
 namespace utils {
 
+/** @brief Manages directories.
+*/
 class CORE_API Dir {
  public:
-  /// Alias for filter function.
+  /// An alias for the filter function.
   using FilterFunction = std::function<bool(const std::string&)>;
 
   /**
-   * @brief Checks if directory exists.
+   * @brief Checks whether a directory exists.
    *
-   * @param path Path of the directory.
+   * @param path The path of the directory.
    *
-   * @return \c true if directory exists, \c false otherwise.
+   * @return True if the directory exists; false otherwise.
    *
-   * @deprecated Will be removed by 10.2020. Please use Exists() instead.
+   * @deprecated Will be removed by 10/2020. Use `Exists()` instead.
    */
   static bool exists(const std::string& path);
 
   /**
-   * @brief Checks if directory exists.
+   * @brief Checks whether a directory exists.
    *
-   * @param path Path of the directory.
+   * @param path The path of the directory.
    *
-   * @return true if directory exists, false otherwise.
+   * @return True if the directory exists; false otherwise.
    */
   static bool Exists(const std::string& path);
 
   /**
-   * @brief Removes the directory, deleting all subfolders and files.
+   * @brief Removes a directory and deletes all its subfolders and files.
    *
-   * @param path Path of the directory.
+   * @param path The path of the directory.
    *
-   * @return true if operation is successfull, false otherwise.
+   * @return True if the operation is successful; false otherwise.
    *
-   *  @deprecated Will be removed by 10.2020. Please use Remove() instead.
+   * @deprecated Will be removed by 10/2020. Use `Remove()` instead.
    */
   static bool remove(const std::string& path);
 
   /**
-   * @brief Removes the directory, deleting all subfolders and files.
+   * @brief Removes a directory and deletes all its subfolders and files.
    *
-   * @param path Path of the directory.
+   * @param path The path of the directory.
    *
-   * @return \c true if operation is successfull, \c false otherwise.
+   * @return True if the operation is successful; false otherwise.
    */
   static bool Remove(const std::string& path);
 
   /**
-   * @brief Creates the directory including all required directories on
-   * the path.
+   * @brief Creates a directory and all required directories specified
+   * in the path.
    *
-   * @param path Path of the directory.
+   * @param path The path of the directory.
    *
-   * @return \c true if operation is successfull, \c false otherwise.
+   * @return True if the operation is successful; false otherwise.
    *
-   * @deprecated Will be removed by 10.2020. Please use Create() instead.
+   * @deprecated Will be removed by 10/2020. Use `Create()` instead.
    */
   static bool create(const std::string& path);
 
   /**
-   * @brief Creates the directory including all required directories on
-   * the path.
+   * @brief Creates a directory and all required directories specified
+   * in the path.
    *
-   * @param path Path of the directory.
+   * @param path The path of the directory.
    *
-   * @return \c true if operation is successfull, \c false otherwise.
+   * @return True if the operation is successful; false otherwise.
    */
   static bool Create(const std::string& path);
 
   /**
-   * @brief Returns the platform-specific temporary path.
+   * @brief Gets a platform-specific temporary path.
    *
-   * @return The platform specific temporary directory path.
+   * @return The platform-specific temporary path of the directory.
    */
   static std::string TempDirectory();
 
   /**
-   * @brief Check whether the provided file exists.
+   * @brief Checks whether the provided file exists.
    *
-   * @param file_path Path to the file.
+   * @param file_path The path of the file.
    *
-   * @return \c true if any file with the given path exists, \c false otherwise.
+   * @return True if the file with the given path exists; false otherwise.
    */
   static bool FileExists(const std::string& file_path);
 
   /**
-   * @brief Calculates size of the directory. Filter may be applied to exclude
-   * unnecessary files or directories from calculation.
+   * @brief Calculates the size of a directory.
    *
-   * @param path Path of the directory.
-   * @param filter_fn Filter function.
+   * Use a filter to exclude
+   * unnecessary files or directories from the calculation.
    *
-   * @return Calculated size.
+   * @param path The path of the directory.
+   * @param filter_fn The filter function.
+   *
+   * @return The calculated size.
    */
   static uint64_t Size(const std::string& path, FilterFunction filter_fn = {});
 };