Add docstrings and improve readability to make the source code more welcoming to newcomers.

QBitNinja/ActionDisposable.cs

@@ -8,23 +8,24 @@ namespace QBitNinja
 {
     public class ActionDisposable : IDisposable
     {
-        Action _Act;
+        readonly Action _Act;
+
         public ActionDisposable(Action act)
         {
             _Act = act;
         }
+
         public ActionDisposable(Action start, Action act)
         {
             start();
             _Act = act;
         }
+
         #region IDisposable Members
-
         public void Dispose()
         {
             _Act();
         }
-
         #endregion
     }
 }

QBitNinja/CacheBlocksRepository.cs

@@ -11,43 +11,45 @@ namespace QBitNinja
 {
     public class CacheBlocksRepository : IBlocksRepository
     {
-        private IBlocksRepository _Repo;
+        private readonly IBlocksRepository _Repo;
 
         public CacheBlocksRepository(IBlocksRepository repo)
         {
-            if(repo == null)
-                throw new ArgumentNullException("repo");
-            this._Repo = repo;
+            this._Repo = repo ?? throw new ArgumentNullException("repo");
         }
 
-        List<Tuple<uint256, Block>> _LastAsked = new List<Tuple<uint256, Block>>();
+        List<Tuple<uint256, Block>> _LastAsked = new List<Tuple<uint256, Block>>();  // A cache of blocks.
 
 
 		#region IBlocksRepository Members
 
-		int MaxBlocks = 70;
+		static readonly int MaxBlocks = 70;  // The maximum number of blocks that may be cached.
 
-        public IEnumerable<NBitcoin.Block> GetBlocks(IEnumerable<NBitcoin.uint256> hashes, CancellationToken cancellation)
+        public IEnumerable<NBitcoin.Block> GetBlocks(IEnumerable<NBitcoin.uint256> hashes, CancellationToken cancellationToken)
         {
             var asked = hashes.ToList();
-			if(asked.Count > MaxBlocks)
-				return _Repo.GetBlocks(hashes, cancellation);
+
+			if (asked.Count > MaxBlocks)  // Asked for more than fit in the cache size, no point in checking cache.
+				return _Repo.GetBlocks(hashes, cancellationToken);  // Fetch from repo instead.
+
             var lastAsked = _LastAsked;
 
-            if(lastAsked != null && asked.SequenceEqual(lastAsked.Select(a => a.Item1)))
+            if (lastAsked != null && asked.SequenceEqual(lastAsked.Select(a => a.Item1)))
                 return lastAsked.Select(l=>l.Item2);
-            var blocks = _Repo.GetBlocks(hashes, cancellation).ToList();
-            if(blocks.Count < 5)
+
+            var blocks = _Repo.GetBlocks(hashes, cancellationToken).ToList();
+
+            if (blocks.Count < 5)  // Shouldn't this number match 'MaxBlocks = 70' ?
             {
                 _LastAsked = blocks.Select(b => Tuple.Create(b.GetHash(), b)).ToList();
             }
             else
             {
                 _LastAsked = null;
             }
+
             return blocks;
         }
-
         #endregion
     }
 }

QBitNinja/ChainTable.cs

@@ -10,31 +10,27 @@
 namespace QBitNinja
 {
     /// <summary>
-    /// Such table can store data keyed by Height/BlockId/TransactionId, and range query them 
+    /// Wraps an Azure table that may store data keyed by Height/BlockId/TransactionId, and allows for range queries against it.
     /// </summary>
     public class ChainTable<T>
     {
         private readonly JsonSerializerSettings serializerSettings;
-        readonly CloudTable _cloudTable;
+        readonly CloudTable _cloudTable;  // An Azure table
+
         public ChainTable(CloudTable cloudTable, Network network)
         {
             if(cloudTable == null)
                 throw new ArgumentNullException("cloudTable");
             if (network == null)
                 throw new ArgumentNullException(nameof(network));
-            JsonSerializerSettings serializerSettings = new JsonSerializerSettings();
+
+            var serializerSettings = new JsonSerializerSettings();
             QBitNinja.Serializer.RegisterFrontConverters(serializerSettings, network);
             this.serializerSettings = serializerSettings;
             _cloudTable = cloudTable;
         }
 
-        public CloudTable Table
-        {
-            get
-            {
-                return _cloudTable;
-            }
-        }
+        public CloudTable Table => _cloudTable;
 
         public Scope Scope
         {
@@ -50,8 +46,6 @@ public void Create(ConfirmedBalanceLocator locator, T item)
             Table.Execute(TableOperation.InsertOrReplace(entity));
         }
 
-
-
         public void Delete(ConfirmedBalanceLocator locator)
         {
             var entity = new DynamicTableEntity(Escape(Scope), Escape(locator))
@@ -60,15 +54,16 @@ public void Delete(ConfirmedBalanceLocator locator)
             };
             Table.Execute(TableOperation.Delete(entity));
         }
+
         public void Delete()
         {
-            foreach(var entity in Table.ExecuteQuery(new TableQuery()
+            var tableQuery = new TableQuery()
             {
                 FilterString = TableQuery.GenerateFilterCondition("PartitionKey", QueryComparisons.Equal, Escape(Scope))
-            }))
-            {
+            };
+
+            foreach (var entity in Table.ExecuteQuery(tableQuery))
                 Table.Execute(TableOperation.Delete(entity));
-            }
         }
 
         public IEnumerable<T> Query(ChainBase chain, BalanceQuery query = null)
@@ -95,6 +90,7 @@ private string ParseData(DynamicTableEntity entity)
             }
             return builder.ToString();
         }
+
         private void PutData(DynamicTableEntity entity, string str)
         {
             int i = 0;

QBitNinja/CrudTable.cs

@@ -28,13 +28,14 @@ public CrudTableFactory(JsonSerializerSettings serializerSettings, Func<CloudTab
         }
 
         readonly Func<CloudTable> _createTable;
+
         public Scope Scope
         {
             get;
             private set;
         }
 
-        private JsonSerializerSettings serializerSettings;
+        private readonly JsonSerializerSettings serializerSettings;
 
         public CrudTable<T> GetTable<T>(string tableName)
         {
@@ -45,6 +46,12 @@ public CrudTable<T> GetTable<T>(string tableName)
             };
         }
     }
+
+    /// <summary>
+    /// Wraps an Azure CloudTable, offering CRUD operations for objects of a specific type, automatically
+    /// serializing to and from JSON when querying the CloudTable.
+    /// </summary>
+    /// <typeparam name="T"></typeparam>
     public class CrudTable<T>
     {
         public CrudTable(CloudTable table, JsonSerializerSettings serializerSettings)
@@ -53,7 +60,7 @@ public CrudTable(CloudTable table, JsonSerializerSettings serializerSettings)
                 throw new ArgumentNullException("table");
             if (serializerSettings == null)
                 throw new ArgumentNullException(nameof(serializerSettings));
-            _table = table;
+            Table = table;
             Scope = new Scope();
             this.serializerSettings = serializerSettings;
         }
@@ -64,14 +71,12 @@ public Scope Scope
             set;
         }
 
-        private JsonSerializerSettings serializerSettings;
-        private readonly CloudTable _table;
+        private readonly JsonSerializerSettings serializerSettings;
+
         public CloudTable Table
         {
-            get
-            {
-                return _table;
-            }
+            get;
+            private set;
         }
 
         public async Task<bool> CreateAsync(string itemId, T item, bool orReplace = true)
@@ -82,9 +87,9 @@ public async Task<bool> CreateAsync(string itemId, T item, bool orReplace = true
                 var entity = new DynamicTableEntity(Escape(Scope), Escape(itemId))
                 {
                     Properties =
-                {
-                    new KeyValuePair<string,EntityProperty>("data",new EntityProperty(callbackStr))
-                }
+                    {
+                        new KeyValuePair<string, EntityProperty>("data", new EntityProperty(callbackStr))
+                    }
                 };
                 await Table.ExecuteAsync(orReplace ? TableOperation.InsertOrReplace(entity) : TableOperation.Insert(entity)).ConfigureAwait(false);
             }
@@ -118,7 +123,7 @@ public void Delete()
             }
         }
 
-        void Ignore(int errorCode, Action act)
+        private void Ignore(int errorCode, Action act)
         {
             try
             {
@@ -130,6 +135,7 @@ void Ignore(int errorCode, Action act)
                     throw;
             }
         }
+
         public bool Delete(string itemId, bool includeChildren = false)
         {
             try
@@ -140,8 +146,8 @@ public bool Delete(string itemId, bool includeChildren = false)
                 }));
                 if (includeChildren)
                 {
-                    var children = Scope.GetChild(itemId);
-                    foreach (var child in Table.ExecuteQuery(AllInScope(children)))
+                    var childScope = Scope.GetChild(itemId);  // 'itemId' can be a  path.
+                    foreach (var child in Table.ExecuteQuery(AllInScope(childScope)))
                     {
                         Ignore(404, () => Table.Execute(TableOperation.Delete(child)));
                     }
@@ -156,11 +162,11 @@ public bool Delete(string itemId, bool includeChildren = false)
             return true;
         }
 
-        private static TableQuery AllInScope(QBitNinja.Scope children)
+        private static TableQuery AllInScope(QBitNinja.Scope scope)
         {
             return new TableQuery()
             {
-                FilterString = TableQuery.GenerateFilterCondition("PartitionKey", QueryComparisons.Equal, Escape(children))
+                FilterString = TableQuery.GenerateFilterCondition("PartitionKey", QueryComparisons.Equal, Escape(scope))
             };
         }
 
@@ -185,8 +191,6 @@ private static string Escape(string key)
             return result;
         }
 
-
-
         public async Task<T> ReadOneAsync(string item)
         {
             var e = (await Table.ExecuteAsync(TableOperation.Retrieve(Escape(Scope), Escape(item))).ConfigureAwait(false)).Result as DynamicTableEntity;
@@ -195,12 +199,10 @@ public async Task<T> ReadOneAsync(string item)
             return JsonConvert.DeserializeObject<T>(e.Properties["data"].StringValue, serializerSettings);
         }
 
-
         public T ReadOne(string item)
         {
             try
             {
-
                 return ReadOneAsync(item).Result;
             }
             catch (AggregateException aex)
@@ -210,6 +212,9 @@ public T ReadOne(string item)
             }
         }
 
+        /// <summary>
+        /// Get a CrudTable that is scoped to some nested path.
+        /// </summary>
         public CrudTable<T> GetChild(params string[] children)
         {
             return new CrudTable<T>(Table, serializerSettings)