Modify documentation (core/include/cache) (#628)

Relates-to: OLPEDGE-860

Signed-off-by: Halyna Dumych <[email protected]>

Author: HalynaDumych

olp-cpp-sdk-core/include/olp/core/cache/CacheSettings.h

@@ -28,7 +28,7 @@ namespace olp {
 namespace cache {
 
 /**
- * @brief Options for opening the disk cache.
+ * @brief Options for opening a disk cache.
  */
 enum OpenOptions : unsigned char {
   Default = 0x00,  /*!< Opens the disk cache in the read-write mode. */
@@ -45,63 +45,74 @@ struct CacheSettings {
    *
    * If this parameter is not set, the downloaded data is stored
    * only in the in-memory cache that is limited by `#max_memory_cache_size`.
+   *
    * @deprecated Use #disk_path_mutable instead.
    */
   OLP_SDK_DEPRECATED("Use disk_path_mutable instead. Will be removed 03.2020")
   boost::optional<std::string> disk_path = boost::none;
 
   /**
-   * @brief The path to the mutable (read-write) on-disk cache where the
-   * SDK will cache and lookup the content. You should have write permissions.
+   * @brief The path to the mutable (read-write) on-disk cache where
+   * the SDK caches and lookups the content.
+   *
+   * You should have write permissions.
    *
    * If this parameter is not set, the downloaded data is stored
    * only in the in-memory cache that is limited by `#max_memory_cache_size`.
    */
   boost::optional<std::string> disk_path_mutable = boost::none;
 
   /**
-   * @brief Set the upper limit of disk space to use for persistent stores in
-   * bytes. Default is 32 MB. Set it to std::uint64_t(-1) in order to never
-   * evict data.
+   * @brief Sets the upper limit (in bytes) of the disk space that is used for
+   * persistent stores.
+   *
+   * The default value is 32 MB. To never evict data, set `max_disk_storage` to
+   * `std::uint64_t(-1)`.
    */
   std::uint64_t max_disk_storage = 1024ull * 1024ull * 32ull;
 
   /**
-   * @brief Set the upper limit of runtime memory to be used before being
-   * written to disk in bytes. Default is 32 Mb.
+   * @brief Sets the upper limit of the runtime memory (in bytes) before it is
+   * written to the disk.
+   *
+   * The default value is 32 MB.
    */
   size_t max_chunk_size = 1024u * 1024u * 32u;
 
   /**
-   * @brief Set the to indicate that continuous flushes to disk are
-   * necessary to preserve maximum data between ignition cycles
+   * @brief Sets the flag to indicate that continuous flushes to the disk are
+   * necessary to preserve maximum data between the ignition cycles.
    */
   bool enforce_immediate_flush = true;
 
   /**
-   * @brief Set the maximum permissable size of one file in storage in bytes.
-   * Default is 2 MB.
+   * @brief Sets the maximum permissible size of one file in the storage (in
+   * bytes).
+   *
+   * The default value is 2 MB.
    */
   size_t max_file_size = 1024u * 1024u * 2u;
 
   /**
-   * @brief Set the upper limit of the in-memory data cache size in bytes.
-   * 0 means the in-memory cache is not used. Default is 1 MB.
+   * @brief Sets the upper limit of the in-memory data cache size (in bytes).
+   *
+   * If set to `0`, the in-memory cache is not used. The default value is 1 MB.
    */
   size_t max_memory_cache_size = 1024u * 1024u;
 
   /**
-   * @brief Set the disk cache open options.
+   * @brief Sets the disk cache open options.
    */
   OpenOptions openOptions = OpenOptions::Default;
 
   /**
-   * @brief Path to the protected (readonly) cache. This cache is used as a
-   * primary cache for lookup. DefaultCache will open this cache in read-only
-   * mode and will not write to it in case the disk_path_mutable is empty. This
-   * path should only be used in case users would like to have a stable fallback
-   * state or offline data that they can always access regardless of the network
-   * state.
+   * @brief The path to the protected (read-only) cache.
+   *
+   * This cache is used as a primary cache for lookup. `DefaultCache` opens this
+   * cache in the read-only mode and does not write to it if
+   * `disk_path_mutable` is empty. Use this cash if you want to have a stable
+   * fallback state or offline data that you can always access regardless of
+   * the network state.
    */
   boost::optional<std::string> disk_path_protected = boost::none;
 };

olp-cpp-sdk-core/include/olp/core/cache/DefaultCache.h

@@ -33,12 +33,12 @@ class DiskCache;
 
 /**
  * @brief A default cache that provides an in-memory LRU cache and persistence
- * of the cached key-value pairs.
+ * of cached key-value pairs.
  *
  * @note By default, the downloaded data is cached only in memory.
  * To enable the persistent cache, define
- * `olp::cache::CacheSettings::disk_path`. On iOS, the path is relative to the
- * application data folder.
+ * `olp::cache::CacheSettings::disk_path`. On iOS, the path is relative to
+ * the application data folder.
  *
  * The default maximum size of the persistent cache is 32 MB. If the entire
  * available disk space should be used, set
@@ -55,86 +55,98 @@ class CORE_API DefaultCache : public KeyValueCache {
  public:
   /*! The storage open result type */
   enum StorageOpenResult {
-    Success,            /*!< operation succeeded */
-    OpenDiskPathFailure /*!< disk cache failure */
+    Success,            /*!< The operation succeeded. */
+    OpenDiskPathFailure /*!< The disk cache failure. */
   };
 
   /**
-   * @brief Parameterized constructor.
-   * @param settings Settings for the cache.
+   * @brief Creates the `DefaultCache` instance.
+   *
+   * @param settings The cache settings.
    */
   DefaultCache(const CacheSettings& settings = CacheSettings());
   ~DefaultCache() override;
 
   /**
-   * @brief Opens the cache to start read/write operations.
+   * @brief Opens the cache to start read and write operations.
    *
-   * @return StorageOpenResult if there were problems opening any of the
-   * provided pathes on the disk.
+   * @return `StorageOpenResult` if there are problems opening any of
+   * the provided paths on the disk.
    */
   StorageOpenResult Open();
 
   /**
-   * @brief Closes the cache for use.
+   * @brief Closes the cache.
    */
   void Close();
 
   /**
-   * @brief Clears the contents of the cache.
-   * @return Returns true if the operation is successfull, false otherwise.
+   * @brief Clears the cache content.
+   *
+   * @return True if the operation is successful; false otherwise.
    */
   bool Clear();
 
   /**
-   * @brief Stores the key-value pair into the cache.
-   * @param key Key for this value
-   * @param value The value of any type
-   * @param encoder A method provided to encode the specified value into a
-   * string
-   * @param expiry Time in seconds to when pair will expire
-   * @return Returns true if the operation is successfull, false otherwise.
+   * @brief Stores the key-value pair in the cache.
+   *
+   * @param key The key for this value.
+   * @param value The value of any type.
+   * @param encoder Encodes the specified value into a string.
+   * @param expiry The expiry time (in seconds) of the key-value pair.
+   *
+   * @return True if the operation is successful; false otherwise.
    */
   bool Put(const std::string& key, const boost::any& value,
            const Encoder& encoder, time_t expiry) override;
 
   /**
-   * @brief Stores the raw binary data as value into the cache.
-   * @param key Key for this value
-   * @param value binary data to be stored
-   * @param expiry Time in seconds to when pair will expire
-   * @return Returns true if the operation is successfull, false otherwise.
+   * @brief Stores the raw binary data as a value in the cache.
+   *
+   * @param key The key for this value.
+   * @param value The binary data that should be stored.
+   * @param expiry The expiry time (in seconds) of the key-value pair.
+   *
+   * @return True if the operation is successful; false otherwise.
    */
   bool Put(const std::string& key, const KeyValueCache::ValueTypePtr value,
            time_t expiry) override;
 
   /**
    * @brief Gets the key-value pair from the cache.
-   * @param key Key to look for
-   * @param decoder A method is provided to decode a value from a string if
-   * needed
+   *
+   * @param key The key that is used to look for the key-value pair.
+   * @param decoder Decodes the value from a string.
+   *
+   * @return The key-value pair.
    */
   boost::any Get(const std::string& key, const Decoder& decoder) override;
 
   /**
    * @brief Gets the key and binary data from the cache.
-   * @param key Key to look for
+   *
+   * @param key The key that is used to look for the binary data.
+   *
+   * @return The key and binary data.
    */
   KeyValueCache::ValueTypePtr Get(const std::string& key) override;
 
   /**
    * @brief Removes the key-value pair from the cache.
-   * @param key Key for the value to remove from cache
    *
-   * @return Returns true if the operation is successfull, false otherwise.
+   * @param key The key for the value.
+   *
+   * @return True if the operation is successful; false otherwise.
    */
   bool Remove(const std::string& key) override;
 
   /**
-   * @brief Removes the values with the keys matching the given
+   * @brief Removes the values with the keys that match the given
    * prefix from the cache.
-   * @param prefix Prefix to look for
    *
-   * @return Returns true on removal, false otherwise.
+   * @param prefix The prefix that matches the keys.
+   *
+   * @return True if the values are removed; false otherwise.
    */
   bool RemoveKeysWithPrefix(const std::string& prefix) override;
 

olp-cpp-sdk-core/include/olp/core/cache/KeyValueCache.h

@@ -36,68 +36,89 @@ using Encoder = std::function<std::string()>;
 using Decoder = std::function<boost::any(const std::string&)>;
 
 /**
- * @brief Interface for cache expecting a key,value pair.
+ * @brief An interface for a cache that expects a key-value pair.
  */
 class CORE_API KeyValueCache {
  public:
-  /// No expiry by default.
+  /**
+   * @brief The expiry time of the key-value pair.
+   *
+   * By default, the key-value pair has no expiry time.
+   */
   static constexpr time_t kDefaultExpiry = std::numeric_limits<time_t>::max();
-  /// Value type to be stored in the DB.
+
+  /**
+   * @brief The value type that is stored in the DB.
+   */
   using ValueType = std::vector<unsigned char>;
-  /// Shared pointer type to the DB entry.
+
+  /**
+   * @brief The shared pointer type of the DB entry.
+   */
   using ValueTypePtr = std::shared_ptr<ValueType>;
 
   virtual ~KeyValueCache() = default;
 
   /**
-   * @brief Store key,value pair into the cache
-   * @param key Key for this value
-   * @param value The value of any type
-   * @param encoder A method provided to encode the specified value into a
-   * string
-   * @param expiry Time in seconds to when pair will expire
-   * @return Returns true if the operation is successfull, false otherwise.
+   * @brief Stores the key-value pair in the cache.
+   *
+   * @param key The key for this value.
+   * @param value The value of any type.
+   * @param encoder Encodes the specified value into a string.
+   * @param expiry The expiry time (in seconds) of the key-value pair.
+   *
+   * @return True if the operation is successful; false otherwise.
    */
   virtual bool Put(const std::string& key, const boost::any& value,
                    const Encoder& encoder, time_t expiry = kDefaultExpiry) = 0;
 
   /**
-   * @brief Store raw binary data as value into the cache
-   * @param key Key for this value
-   * @param value binary data to be stored
-   * @param expiry Time in seconds to when pair will expire
-   * @return Returns true if the operation is successfull, false otherwise.
+   * @brief Stores the raw binary data as a value in the cache.
+   *
+   * @param key The key for this value.
+   * @param value The binary data that should be stored.
+   * @param expiry The expiry time (in seconds) of the key-value pair.
+   *
+   * @return True if the operation is successful; false otherwise.
    */
   virtual bool Put(const std::string& key, const ValueTypePtr value,
                    time_t expiry = kDefaultExpiry) = 0;
 
   /**
-   * @brief Get key,value pair from the cache
-   * @param key Key to look for
-   * @param decoder A method is provided to decode a value from a string if
-   * needed
+   * @brief Gets the key-value pair from the cache.
+   *
+   * @param key The key that is used to look for the key-value pair.
+   * @param decoder Decodes the value from a string.
+   *
+   * @return The key-value pair.
    */
   virtual boost::any Get(const std::string& key, const Decoder& encoder) = 0;
 
   /**
-   * @brief Get key and binary data from the cache
-   * @param key Key to look for
+   * @brief Gets the key and binary data from the cache.
+   *
+   * @param key The key that is used to look for the binary data.
+   *
+   * @return The key and binary data.
    */
   virtual ValueTypePtr Get(const std::string& key) = 0;
 
   /**
-   * @brief Remove a key,value pair from the cache
-   * @param key Key for the value to remove from cache
+   * @brief Removes the key-value pair from the cache.
    *
-   * @return Returns true if the operation is successfull, false otherwise.
+   * @param key The key for the value.
+   *
+   * @return True if the operation is successful; false otherwise.
    */
   virtual bool Remove(const std::string& key) = 0;
 
   /**
-   * @brief Remove values with keys matching the given prefix from the cache
-   * @param prefix Prefix to look for
+   * @brief Removes the values with the keys that match the given
+   * prefix from the cache.
+   *
+   * @param prefix The prefix that matches the keys.
    *
-   * @return Returns true on removal, false otherwise.
+   * @return True if the values are removed; false otherwise.
    */
   virtual bool RemoveKeysWithPrefix(const std::string& prefix) = 0;
 };