Add comments to private fields and methods

Author: hjgraca

libraries/src/AWS.Lambda.Powertools.Idempotency/AWS.Lambda.Powertools.Idempotency.csproj

@@ -43,8 +43,4 @@
         <None Include="../../AWSLogo128x128.png" Pack="true" Visible="false" PackagePath="" />
     </ItemGroup>
 
-    <ItemGroup>
-      <Folder Include="Output\" />
-    </ItemGroup>
-
 </Project>

libraries/src/AWS.Lambda.Powertools.Idempotency/Idempotency.cs

@@ -38,16 +38,27 @@ public sealed class Idempotency
     /// </summary>
     public BasePersistenceStore PersistenceStore { get; private set; } = null!;
 
+    /// <summary>
+    /// Idempotency Constructor
+    /// </summary>
+    /// <param name="powertoolsConfigurations"></param>
     internal Idempotency(IPowertoolsConfigurations powertoolsConfigurations)
     {
         powertoolsConfigurations.SetExecutionEnvironment(this);
     }
-
+    /// <summary>
+    /// Set Idempotency options
+    /// </summary>
+    /// <param name="options"></param>
     private void SetConfig(IdempotencyOptions options)
     {
         IdempotencyOptions = options;
     }
 
+    /// <summary>
+    /// Set Persistence Store
+    /// </summary>
+    /// <param name="persistenceStore"></param>
     private void SetPersistenceStore(BasePersistenceStore persistenceStore)
     {
         PersistenceStore = persistenceStore;
@@ -79,10 +90,21 @@ public static void Configure(Action<IdempotencyBuilder> configurationAction)
     /// </summary>
     public class IdempotencyBuilder
     {
+        /// <summary>
+        /// Holds Idempotency options
+        /// </summary>
         private IdempotencyOptions _options;
+        /// <summary>
+        /// Persistence Store
+        /// </summary>
         private BasePersistenceStore _store;
-
+        /// <summary>
+        /// Exposes Idempotency options
+        /// </summary>
         internal IdempotencyOptions Options => _options;
+        /// <summary>
+        /// Exposes Persistence Store
+        /// </summary>
         internal BasePersistenceStore Store => _store;
 
         /// <summary>

libraries/src/AWS.Lambda.Powertools.Idempotency/IdempotencyOptions.cs

@@ -58,6 +58,16 @@ public class IdempotencyOptions
     /// </summary>
     public string HashFunction { get; }
 
+    /// <summary>
+    /// Constructor of <see cref="IdempotencyOptions"/>.
+    /// </summary>
+    /// <param name="eventKeyJmesPath"></param>
+    /// <param name="payloadValidationJmesPath"></param>
+    /// <param name="throwOnNoIdempotencyKey"></param>
+    /// <param name="useLocalCache"></param>
+    /// <param name="localCacheMaxItems"></param>
+    /// <param name="expirationInSeconds"></param>
+    /// <param name="hashFunction"></param>
     internal IdempotencyOptions(
         string eventKeyJmesPath, 
         string payloadValidationJmesPath, 

libraries/src/AWS.Lambda.Powertools.Idempotency/IdempotencyOptionsBuilder.cs

@@ -7,12 +7,33 @@ namespace AWS.Lambda.Powertools.Idempotency;
 /// </summary>
 public class IdempotencyOptionsBuilder
 {
+    /// <summary>
+    /// Default maximum number of items in the local cache.
+    /// </summary>
     private readonly int _localCacheMaxItems = 256;
+    /// <summary>
+    /// Local cache enabled
+    /// </summary>
     private bool _useLocalCache;
+    /// <summary>
+    /// Default expiration in seconds.
+    /// </summary>
     private long _expirationInSeconds = 60 * 60; // 1 hour
+    /// <summary>
+    /// Event key JMESPath expression.
+    /// </summary>
     private string _eventKeyJmesPath;
+    /// <summary>
+    /// Payload validation JMESPath expression.
+    /// </summary>
     private string _payloadValidationJmesPath;
+    /// <summary>
+    /// Throw exception if no idempotency key is found.
+    /// </summary>
     private bool _throwOnNoIdempotencyKey;
+    /// <summary>
+    /// Default Hash function
+    /// </summary>
     private string _hashFunction = "MD5";
 
     /// <summary>

libraries/src/AWS.Lambda.Powertools.Idempotency/Internal/IdempotencyAspectHandler.cs

@@ -23,12 +23,29 @@ namespace AWS.Lambda.Powertools.Idempotency.Internal;
 
 internal class IdempotencyAspectHandler<T>
 {
+    /// <summary>
+    /// Max retries
+    /// </summary>
     private const int MaxRetries = 2;
-
+    /// <summary>
+    /// Delegate to execute the calling handler
+    /// </summary>
     private readonly Func<Task<T>> _target;
+    /// <summary>
+    /// Request payload
+    /// </summary>
     private readonly JsonDocument _data;
+    /// <summary>
+    /// Persistence store
+    /// </summary>
     private readonly BasePersistenceStore _persistenceStore;
 
+    /// <summary>
+    /// IdempotencyAspectHandler constructor
+    /// </summary>
+    /// <param name="target"></param>
+    /// <param name="functionName"></param>
+    /// <param name="payload"></param>
     public IdempotencyAspectHandler(
         Func<Task<T>> target,
         string functionName,
@@ -170,6 +187,11 @@ private Task<T> HandleForStatus(DataRecord record)
         }
     }
 
+    /// <summary>
+    /// Get the function's response and save it to the persistence layer
+    /// </summary>
+    /// <returns>Result from Handler delegate</returns>
+    /// <exception cref="IdempotencyPersistenceLayerException"></exception>
     private async Task<T> GetFunctionResponse()
     {
         T response;

libraries/src/AWS.Lambda.Powertools.Idempotency/Internal/LRUCache.cs

@@ -18,9 +18,24 @@ internal sealed class LRUCache<TKey, TValue>
     /// </summary>
     private const int DefaultCapacity = 255;
 
+    /// <summary>
+    /// Shared synchronization object
+    /// </summary>
     private readonly object _lockObj = new();
+    
+    /// <summary>
+    /// Maximum number of elements to cache.
+    /// </summary>
     private readonly int _capacity;
+    
+    /// <summary>
+    /// Dictionary to record the key and its data entry (O(1))
+    /// </summary>
     private readonly Dictionary<TKey, Entry> _cacheMap;
+    
+    /// <summary>
+    /// Linked list that tracks LRU items (O(1))
+    /// </summary>
     private readonly LinkedList<TKey> _cacheList;
 
     /// <summary>
@@ -109,6 +124,10 @@ public void Set(TKey key, TValue value)
         }
     }
 
+    /// <summary>
+    /// Deletes the specified key and value to the cache.
+    /// </summary>
+    /// <param name="key">The key of the element to remove.</param>
     public void Delete(TKey key)
     {
         lock (_lockObj)
@@ -118,6 +137,9 @@ public void Delete(TKey key)
         }
     }
 
+    /// <summary>
+    /// Count of items in Cache
+    /// </summary>
     public int Count
     {
         get
@@ -129,6 +151,10 @@ public int Count
         }
     }
 
+    /// <summary>
+    /// Move to most recent spot (head) in Linked List
+    /// </summary>
+    /// <param name="node"></param>
     private void Touch(LinkedListNode<TKey> node)
     {
         lock (_lockObj)
@@ -141,6 +167,9 @@ private void Touch(LinkedListNode<TKey> node)
         }
     }
 
+    /// <summary>
+    /// Linked List Element
+    /// </summary>
     private struct Entry
     {
         public readonly LinkedListNode<TKey> Node;

libraries/src/AWS.Lambda.Powertools.Idempotency/Persistence/BasePersistenceStore.cs

@@ -33,12 +33,23 @@ namespace AWS.Lambda.Powertools.Idempotency.Persistence;
 /// </summary>
 public abstract class BasePersistenceStore : IPersistenceStore
 {
+    /// <summary>
+    /// Idempotency Options
+    /// </summary>
     private IdempotencyOptions _idempotencyOptions = null!;
+    
+    /// <summary>
+    /// Function name
+    /// </summary>
     private string _functionName;
     /// <summary>
     /// Boolean to indicate whether or not payload validation is enabled
     /// </summary>
     protected bool PayloadValidationEnabled;
+    
+    /// <summary>
+    /// LRUCache
+    /// </summary>
     private LRUCache<string, DataRecord> _cache = null!;
 
     /// <summary>
@@ -197,6 +208,12 @@ private void ValidatePayload(JsonDocument data, DataRecord dataRecord)
         }
     }
 
+    /// <summary>
+    /// Retrieve data record from cache
+    /// </summary>
+    /// <param name="idempotencyKey">Idempotency key</param>
+    /// <param name="now">DateTime Offset</param>
+    /// <returns>DataRecord instance</returns>
     private DataRecord RetrieveFromCache(string idempotencyKey, DateTimeOffset now)
     {
         if (!_idempotencyOptions.UseLocalCache)
@@ -212,6 +229,11 @@ private DataRecord RetrieveFromCache(string idempotencyKey, DateTimeOffset now)
         }
         return null;
     }
+    
+    /// <summary>
+    /// Deletes item from cache
+    /// </summary>
+    /// <param name="idempotencyKey"></param>
     private void DeleteFromCache(string idempotencyKey)
     {
         if (!_idempotencyOptions.UseLocalCache)
@@ -282,6 +304,11 @@ private string GetHashedIdempotencyKey(JsonDocument data)
         return _functionName + "#" + hash;
     }
 
+    /// <summary>
+    /// Check if the provided data is missing an idempotency key.
+    /// </summary>
+    /// <param name="data"></param>
+    /// <returns>True if the Idempotency key is missing</returns>
     private static bool IsMissingIdemPotencyKey(JsonElement data)
     {
         return data.ValueKind == JsonValueKind.Null || data.ValueKind == JsonValueKind.Undefined
@@ -307,6 +334,12 @@ internal string GenerateHash(JsonElement data)
         return hash;
     }
 
+    /// <summary>
+    /// Get a hash of the provided string using the specified hash algorithm
+    /// </summary>
+    /// <param name="hashAlgorithm"></param>
+    /// <param name="input"></param>
+    /// <returns>Hashed representation of the provided string</returns>
     private static string GetHash(HashAlgorithm hashAlgorithm, string input)
     {
         // Convert the input string to a byte array and compute the hash.

libraries/src/AWS.Lambda.Powertools.Idempotency/Persistence/DataRecord.cs

@@ -22,6 +22,9 @@ namespace AWS.Lambda.Powertools.Idempotency.Persistence;
 /// </summary>
 public class DataRecord
 {
+    /// <summary>
+    /// Status
+    /// </summary>
     private readonly string _status;
 
     /// <summary>