Document observation protocols

Author: vadymmarkov

Source/Shared/Storage/KeyObservationRegistry.swift

@@ -1,16 +1,28 @@
 import Foundation
 
+/// A protocol used for adding and removing key observations
 public protocol KeyObservationRegistry {
   associatedtype S: StorageAware
 
+  /**
+   Registers observation closure which will be removed automatically
+   when the weekly captured observer has been deallocated.
+   - Parameter observer: Any object that helps to determine if the observation is still valid
+   - Parameter key: Unique key to identify the object in the cache
+   - Parameter closure: Observation closure
+   - Returns: Token used to cancel the observation and remove the observation closure
+   */
   @discardableResult
   func addObserver<O: AnyObject>(
     _ observer: O,
     forKey key: String,
     closure: @escaping (O, S, KeyChange<S.T>) -> Void
   ) -> ObservationToken
 
+  /// Removes observer by the given key.
   func removeObserver(forKey key: String)
+
+  /// Removes all registered key observers
   func removeAllKeyObservers()
 }
 

Source/Shared/Storage/StorageObservationRegistry.swift

@@ -1,14 +1,23 @@
 import Foundation
 
+/// A protocol used for adding and removing storage observations
 public protocol StorageObservationRegistry {
   associatedtype S: StorageAware
 
+  /**
+   Registers observation closure which will be removed automatically
+   when the weekly captured observer has been deallocated.
+   - Parameter observer: Any object that helps to determine if the observation is still valid
+   - Parameter closure: Observation closure
+   - Returns: Token used to cancel the observation and remove the observation closure
+   */
   @discardableResult
   func addStorageObserver<O: AnyObject>(
     _ observer: O,
     closure: @escaping (O, S, StorageChange) -> Void
   ) -> ObservationToken
 
+  /// Removes all registered key observers
   func removeAllStorageObservers()
 }