Grammatical and capitalization changes

Author: Mel W

components/TARGET_PSA/spm/COMPONENT_SPE/handles_manager.h

@@ -27,21 +27,21 @@
 /* -------------------------------- Handle Manager Module ---------------------------- */
 
 /*
- * The Handle Manager module generates and exposes a unique handle
- * identifier (handle) per handle memory (handle_mem) it receives from the user.
- * Then users can use the exposed handle identifier to relate to the "registered"
+ * The Handle Manager module generates and exposes a unique 
+ * identifier (handle) per handle memory (handle_mem) it receives.
+ * You can use the exposed handle identifier to relate to the "registered"
  * handle memory.
  *
- * Users can:
- * - Ask for a unique handle identifier for a given handle memory [handle_create]
+ * You can:
+ * - Ask for a unique handle identifier for a given handle memory [`handle_create`].
  * - Ask for a pointer to the handle memory corresponding to a
- *   handle identifier [handle_get_mem]
- * - Remove a handle from the handle manager module [handle_destroy]
+ *   handle identifier [`handle_get_mem`].
+ * - Remove a handle from the handle manager module [`handle_destroy`].
  *
  * Note:
  * Handle generation is done exclusively.
  * Once you have a handle, you can remove or get its memory non-exclusively.
- * The assumption is that only one context is dealing with a handle after it was
+ * The assumption is that only one context is dealing with a handle after it is
  * generated.
  */
 
@@ -59,9 +59,9 @@ extern "C" {
 
 #define PSA_HANDLE_MGR_INVALID_FRIEND_OWNER     0       // Denoting invalid friend or invalid owner
 
-// Handles manager pool indexes must be in range 0 - 0x7FFF.
-// The reason for this limitation is that the index is stored in the upper 16 bits of a handle,
-// and the most significant bit must be zero to keep handles non negative.
+// Handle manager pool indexes must be in range 0 - 0x7FFF.
+// This is because the index is stored in the upper 16 bits of a handle,
+// and the most significant bit must be zero to keep handles non-negative.
 #define PSA_HANDLE_MGR_MAX_HANDLES_NUM          0x8000
 
 
@@ -70,19 +70,19 @@ extern "C" {
 
 typedef struct psa_handle_item_t {
 
-    psa_handle_t  handle;           /* The user exposed handle [unique identifier] */
-    int32_t       handle_owner;     /* The partition id of the handle creator - allowed to get_mem() / destroy() */
-    int32_t       handle_friend;    /* The partition id of a "friend" partition - allowed to get_mem() */
-    void         *handle_mem;       /* Points to memory allocated by the user */
+    psa_handle_t  handle;           /* The user-exposed handle [unique identifier]. */
+    int32_t       handle_owner;     /* The partition ID of the handle creator. Allowed to get_mem() / destroy(). */
+    int32_t       handle_friend;    /* The partition ID of a "friend" partition. Allowed to get_mem(). */
+    void         *handle_mem;       /* Points to memory allocated by the use.r */
 
 } psa_handle_item_t;
 
 
 typedef struct psa_handle_manager_t {
 
-    uint32_t           handle_generator;    /* A counter supplying handle numbers  */
-    uint32_t           pool_size;           /* The maximum number of handles that pool can contain */
-    psa_handle_item_t *handles_pool;        /* Holding couples of handles and their memory "blocks" */
+    uint32_t           handle_generator;    /* A counter supplying handle numbers.  */
+    uint32_t           pool_size;           /* The maximum number of handles that pool can contain. */
+    psa_handle_item_t *handles_pool;        /* Holds couples of handles and their memory "blocks". */
 
 } psa_handle_manager_t;
 
@@ -109,40 +109,40 @@ handles_pool
 
 
 /*
- * @brief create unique handle identifier
+ * @brief Create unique handle identifier
  *
  * This function generates a unique handle identifier, and **couples** it with the received handle memory.
  * If there is no vacant space for the new handle, the function fails.
  *
  * @note This function is expected to pass since it is always coupled with memory pool allocation of the same size.
  *       In case memory pool allocation fails, this function should not be called.
- *       This function will panic on non vacant space use case.
+ *       This function will panic in the case of non-vacant space use.
  *
  * @param[in] handle_mgr   A pointer to the handle manager object.
- * @param[in] handle_mem   A pointer to a pre-allocated handle memory to get a handle identifier for
- * @param[in] friend_pid   The partition ID which is allowed to `get_mem()` and `destroy()` in addition to the handle owner.
- *                          Use PSA_HANDLE_MGR_INVALID_FRIEND_OWNER to denote there is no friend partition.
- * @return The created handle identifier
+ * @param[in] handle_mem   A pointer to a pre-allocated handle memory for which to get a handle identifier.
+ * @param[in] friend_pid   The partition ID allowed to `get_mem()` and `destroy()` in addition to the handle owner.
+ *                         Use `PSA_HANDLE_MGR_INVALID_FRIEND_OWNER` to denote that there is no friend partition.
+ * @return                 The created handle identifier
  */
 psa_handle_t psa_hndl_mgr_handle_create(psa_handle_manager_t *handle_mgr, void *handle_mem, int32_t friend_pid);
 
 
 /*
- * @brief remove a handle from the handle manager.
+ * @brief Remove a handle from the handle manager.
  *
- * @param handle_mgr   A pointer to the handle manager object
- * @param handle       The handle to be removed
+ * @param handle_mgr   A pointer to the handle manager object.
+ * @param handle       The handle to be removed.
  */
 void psa_hndl_mgr_handle_destroy(psa_handle_manager_t *handle_mgr, psa_handle_t handle);
 
 
 /*
- * @brief dereference handle
+ * @brief De-reference handle
  *
  * This function retrieves the pointer associated with the input <handle>.
  *
- * @note  This function will panic in case caller not allowed to dereference the memory
- *         or handler does not correspond to a valid existing handle
+ * @note  This function will panic if caller is not allowed to de-reference the memory,
+ *        or handler does not correspond to a valid existing handle.
  *
  * @param handle_mgr   A pointer to the handle manager object.
  * @param handle       The handle for which you request the corresponding memory handle.