docs: update CHANGELOG and docstring

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to this project will be documented in this file.
 
+## [Unreleased]
+
+### Features
+
+- Change `Axis` to `Dimension` with a clear distinction between `Ordered` and `Unordered`.
+- Create a `Dictionary` data structure to store and update `Ordered Dimension` efficiently
+- Change the data structure of `MasterSecretKey` and `UserSecretKey` to keep track of subkeys version.
+- Policy does not count the attribute rotations anymore as they are stored in the subkeys.
+- a `UserSecretKey` can now be refreshed without any external `Policy` information.
+
 ## [13.0.0] - 2023-11-06
 
 ### Bug Fixes

src/core/api.rs

@@ -75,8 +75,8 @@ impl Covercrypt {
         )
     }
 
-    /// Renews the keys associated to the given access policy in the master
-    /// keys.
+    /// Generate new keys associated to the given access policy in the master
+    /// keys. User keys will need to be refreshed after this step.
     ///  - `access_policy`  : describe the keys to renew
     ///  - `policy`         : global policy
     ///  - `msk`            : master secret key
@@ -96,7 +96,8 @@ impl Covercrypt {
         )
     }
 
-    /// Removes old keys from the master keys.
+    /// Removes old keys associated to the given master keys from the master
+    /// keys. This will permanently remove access to old ciphers.
     ///  - `access_policy`  : describe the keys to prune
     ///  - `policy`         : global policy
     ///  - `msk`            : master secret key
@@ -114,7 +115,8 @@ impl Covercrypt {
 
     /// Generates a user secret key.
     ///
-    /// A new user secret key does NOT include to old (i.e. rotated) partitions.
+    /// A new user secret key only has the latest keys corresponding to its
+    /// access policy.
     ///
     /// - `msk`           : master secret key
     /// - `access_policy` : user access policy