Several minor docs enhancements

Author: chrisgitiota

components_move/README.md

@@ -5,15 +5,16 @@ within the IOTA Trust Framework. These components are designed to be modular and
 Trust Framework products and community-developed smart contracts.
 
 Modules Overview:
-* `role_map`:   Implements the `RoleMap` struct for role-based access control, allowing mapping of roles to 
+
+* `role_map`:   Implements the `RoleMap` struct for role-based access control, allowing mapping of roles to
                 application specific permissions.
-* `capability`: Defines the `Capability` struct for granting access rights within smart contracts in conjunction with 
+* `capability`: Defines the `Capability` struct for granting access rights within smart contracts in conjunction with
                 the `RoleMap<P>` struct.
 * `timelock`:   Provides the `Timelock` struct for expressing and processing time-based restrictions
 
 ## Role-Based Access Control - The `role_map` and the `capability` Module
 
-The `role_map` module provides the `RoleMap<P>` struct, which is 
+The `role_map` module provides the `RoleMap<P>` struct, which is
 a role-based access control helper that maps unique role identifiers to their associated permissions.
 
 The `capability` module provides the `capability::Capability` struct,
@@ -22,24 +23,26 @@ a capability token that grants access rights defined by one specific role in the
 The `role_map` module directly depends on the `capability` module. Both modules are tight strongly together.
 
 The `RoleMap<P>` struct provides the following functionalities:
-- Uses custom permission types defined by the integrating module using the generic argument `P`
-- Defines an initial role with a custom set of permissions (i.e. for an Admin role) and creates an initial
+
+* Uses custom permission-types, defined by the integrating module, using the generic argument `P`
+* Defines an initial role with a custom set of permissions (i.e. for an Admin role) and creates an initial
   `Capability` for this role to allow later access control administration by the creator of the integrating module
-- Allows to create, delete, and update roles and their permissions
-- Allows to issue, revoke, and destroy `Capability`s associated with a specific role
-- Validates `Capability`s against the defined roles to facilitate proper access control by the integrating module
+* Allows to create, delete, and update roles and their permissions
+* Allows to issue, revoke, and destroy `Capability`s associated with a specific role
+* Validates `Capability`s against the defined roles to facilitate proper access control by the integrating module
   (function `RoleMap.is_capability_valid()`)
-- All functions are access restricted by custom permissions defined during `RoleMap` instantiation
+* All functions are access restricted by custom permissions defined during `RoleMap` instantiation
 
 ### Usage Examples
 
 The [`Counter` example](./examples/counter/README.md) is a very simple example, demonstrating how to use
-`RoleMap` and `Capability` for role based access control. The accompanying 
+`RoleMap` and `Capability` for role based access control. The accompanying
 [test file](./examples/counter/tests/counter_tests.move) demonstrates the Move user experience.
 
-The Trust Framework product *Audit Trails* uses the `RoleMap` to manage access to the audit trail records and their operations, which 
+The Trust Framework product *Audit Trails* uses the `RoleMap` to manage access to the audit trail records and their operations, which
 can be seen as a more complex example:
-* The `RoleMap` is integrated in the `audit_trail::main` module to manage access to the audit trail records and 
-  their operations. See [here](https://github.com/iotaledger/notarization/blob/main/audit-trail-move/sources/audit_trail.move#L208) for an example.
+
+* The `RoleMap` is integrated in the `audit_trail::main` module to manage access to the audit trail records and
+  their operations. See [audit_trail.move](https://github.com/iotaledger/notarization/blob/main/audit-trail-move/sources/audit_trail.move#L208) for an example.
 * The `RoleMap` is created by the `AuditTrail` in it's [create function](https://github.com/iotaledger/notarization/blob/main/audit-trail-move/sources/audit_trail.move#L114).
 * An example for the Move user experience can be found in the [capability_tests.move](https://github.com/iotaledger/notarization/blob/main/audit-trail-move/tests/capability_tests.move) file.

components_move/examples/counter/README.md

@@ -1,8 +1,6 @@
 # RoleMap Integration Example
 
-The Counter example shows how the `RoleMap` can be integrated into 3rd party shared objects
-(or Trust Framework products). In this example the `role_map` and `capability` modules are 
-integrated into a simple shared `Counter` object, as being described
+This Counter example shows how the `role_map::RoleMap` can be integrated into 3rd party shared objects (or Trust Framework products). The example integrates the `role_map` and `capability` modules into a simple shared `Counter` object, as being described
 [here](https://docs.iota.org/developer/iota-101/move-overview/package-upgrades/upgrade#4-guard-function-access).
 
 ## Permissions
@@ -15,20 +13,15 @@ can be found in the [permission.move](./sources/permission.move) file.
 
 ## RoleMap Integration
 
-The integration of the `RoleMap<CounterPermission>` into the target object, which is the `Counter` object in
-this example, requires the following steps.
+The `RoleMap` is used to manage access control to target objects. In this example a target object is a `Counter` object. The integration of the `RoleMap<CounterPermission>` into the target object type (the `Counter` struct), requires the following steps (implementation of the shared `Counter` example can be found in [counter.move](./sources/counter.move)):
 
-The implementation of the shared `Counter` example can be found in the
-[counter.move](./sources/counter.move) file.
-
-The target object needs to:
 * instantiate the `RoleMap` instance in its `create()` function
 * provide the necessary getter and mutator functions for users to access the `RoleMap` instance
-  (function `access()` and `access_mut()` in the [counter.move](./sources/counter.move) file)
+  (function `access()` and `access_mut()` in [counter.move](./sources/counter.move))
 * use the `RoleMap.is_capability_valid()` function to check whether a provided capability has the required permission
-  (used in function `increment()` in the [counter.move](./sources/counter.move) file)
+  (used in function `increment()` in [counter.move](./sources/counter.move))
 
-## User experience and testing the Integration
+## `RoleMap` User experience and testing the Integration
 
 The accompanying [counter_tests.move](./tests/counter_tests.move) file demonstrates the
 user experience of Move users interacting with the shared `Counter` object via the integrated

components_move/examples/counter/sources/counter.move

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 IOTA Stiftung
 // SPDX-License-Identifier: Apache-2.0
 
-/// Simple example Permissions for a shared counter
+/// Simple shared counter to demonstrate role_mao::RoleMap integration
 #[test_only]
 module tf_components::counter;
 
@@ -25,7 +25,7 @@ public fun create(ctx: &mut TxContext): (Capability, ID) {
     let counter_id = object::uid_to_inner(&counter_uid);
 
     // Create a `CapabilityAdminPermissions` instance to configure the permissions
-    // that will be needed by users to issue and revoke cabilities with the `RoleMap`.
+    // that will be needed by users to issue and revoke capabilities with the `RoleMap`.
     //
     // There are two actions that need to be configured with a permission of your choice:
     // * `add`: Permission required to add (issue) a new capability
@@ -48,8 +48,8 @@ public fun create(ctx: &mut TxContext): (Capability, ID) {
     //
     // In this example we allow to use all three actions with the `ManageRoles` permission
     // for the sake of simplicity. In a real world application you would probably have action
-    // specific permissiions like `AddRoles`, `DeleteRoles` and `UpdateRoles` like we did
-    // above to specifify the `CapabilityAdminPermissions`.
+    // specific permissions like `AddRoles`, `DeleteRoles` and `UpdateRoles` like we did
+    // above to specify the `CapabilityAdminPermissions`.
     //
     let role_admin_permissions = role_map::new_role_admin_permissions(
         permission::manage_roles(),

components_move/examples/counter/tests/counter_tests.move

@@ -11,12 +11,6 @@ use tf_components::counter::{Self, Counter};
 use tf_components::counter_permission as permission;
 
 /// Test capability lifecycle: creation, usage, revocation and destruction in a complete workflow.
-///
-/// This test validates:
-/// - A capability can be created for the `counter-admin` role
-/// - The Capability can be used to perform authorized actions
-/// - The Capability can be revoked
-/// - The Capability can be destroyed thereafter
 #[test]
 fun test_capability_lifecycle() {
     let super_admin_user = @0xAD;

components_move/sources/role_map.move

@@ -1,22 +1,22 @@
 // Copyright (c) 2026 IOTA Stiftung
 // SPDX-License-Identifier: Apache-2.0
 
-/// A role-based access control helper mapping unique role identifiers to their associated permissions.
+/// A role-based access control helper, mapping unique role identifiers to their associated permissions.
 ///
-/// Provides the following functionalities:
-/// - Define an initial role with a custom set of permissions (i.e. an Admin role).
-/// - Use custom permission types defined by the integrating module using the generic parameter `P`.
-/// - Create, delete, and update roles and their permissions
-/// - Issue, revoke, and destroy `tf_components::capability`s associated with a specific role.
-/// - Validate `tf_components::capability`s against the defined roles to facilitate proper access control by other modules
+/// A `RoleMap<P>` provides the following functionalities:
+/// - Uses custom permission-types, defined by the integrating module, using the generic argument `P`
+/// - Defines an initial role with a custom set of permissions (i.e. for an Admin role) and creates an initial
+///   `Capability` for this role to allow later access control administration by the creator of the integrating module
+/// - Allows to create, delete, and update roles and their permissions
+/// - Allows to issue, revoke, and destroy `Capability`s associated with a specific role
+/// - Validates `Capability`s against the defined roles to facilitate proper access control by the integrating module
 ///   (function `RoleMap.is_capability_valid()`)
-/// - All functions are access restricted by custom permissions defined during `RoleMap` instantiation.
+/// - All functions are access restricted by custom permissions defined during `RoleMap` instantiation
 ///
 /// Examples:
 /// - The TF product Audit Trails uses `RoleMap` to manage access to the audit trail records and their operations.
-/// - The `tf_components` package README provides a "Hello World" like simple usage example
-///   ([Counter Example](../README.md#rolemap-integration-example)).
-
+/// - The `TfComponents` package provides a "Hello World" like simple [`Counter` example](../examples/counter/README.md).
+///
 module tf_components::role_map;
 
 use iota::clock::Clock;

components_move/sources/timelock.move

@@ -4,12 +4,7 @@
 /// # Timelock Unlock Condition Module
 ///
 /// This module implements a timelock mechanism that restricts access to resources
-/// until a specified time has passed. It provides functionality to create and validate
-/// different types of time-based locks:
-///
-/// - Simple time locks that unlock at a specific Unix timestamp
-/// - UntilDestroyed lock that never unlocks until the locked object is destroyed
-/// - None lock that is not locked
+/// until a specified time has passed.
 module tf_components::timelock;
 
 use iota::clock::{Self, Clock};
@@ -188,7 +183,7 @@ public fun is_valid_period_ms(unix_time: u64, current_time: u64): bool {
 }
 
 #[test_only]
-/// Test helper to delete a TimeLock for testing purposes, especially usefull for Infinite locks.
+/// Test helper to delete a TimeLock for testing purposes, especially useful for Infinite locks.
 public fun destroy_for_testing(lock: TimeLock) {
     match (lock) {
         TimeLock::UnlockAt(_time) => {},

components_move/tests/core_test_utils.move

@@ -1,6 +1,7 @@
 // Copyright (c) 2026 IOTA Stiftung
 // SPDX-License-Identifier: Apache-2.0
 
+#[test_only]
 module tf_components::core_test_utils;
 
 use iota::object::id_from_bytes;
@@ -116,4 +117,4 @@ public fun create_test_role_map(
     (role_map, admin_cap, target_key)
 }
 
-// --------------------------- Helper Fuctions -------------------------------------------------------------------
+// --------------------------- Helper Functions -------------------------------------------------------------------