Merge pull request step-up-labs#213 from cabauman/xml-docs-and-minor-optimizations

xml doc fixes and minor optimizations

Author: bezysoftware

src/Firebase/FirebaseClient.cs

@@ -25,7 +25,7 @@ public class FirebaseClient : IDisposable
         /// Initializes a new instance of the <see cref="FirebaseClient"/> class.
         /// </summary>
         /// <param name="baseUrl"> The base url. </param>
-        /// <param name="offlineDatabaseFactory"> Offline database. </param>  
+        /// <param name="options"> The Firebase options. </param>  
         public FirebaseClient(string baseUrl, FirebaseOptions options = null)
         {
             this.Options = options ?? new FirebaseOptions();

src/Firebase/FirebaseKeyGenerator.cs

@@ -7,7 +7,7 @@ namespace Firebase.Database
     /// Offline key generator which mimics the official Firebase generators. 
     /// Credit: https://github.com/bubbafat/FirebaseSharp/blob/master/src/FirebaseSharp.Portable/FireBasePushIdGenerator.cs
     /// </summary>
-    public class FirebaseKeyGenerator 
+    public static class FirebaseKeyGenerator 
     {
         // Modeled after base64 web-safe chars, but ordered by ASCII.
         private const string PushCharsString = "-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz";

src/Firebase/FirebaseObject.cs

@@ -1,7 +1,7 @@
 namespace Firebase.Database
 {
     /// <summary>
-    /// Holds the object of type <typeparam name="T" /> along with its key. 
+    /// Holds the object of type <typeparamref name="T" /> along with its key. 
     /// </summary>
     /// <typeparam name="T"> Type of the underlying object. </typeparam> 
     public class FirebaseObject<T> 

src/Firebase/Http/HttpClientExtensions.cs

@@ -41,7 +41,7 @@ public static async Task<IReadOnlyCollection<FirebaseObject<T>>> GetObjectCollec
 
                 if (dictionary == null)
                 {
-                    return new FirebaseObject<T>[0];
+                    return Array.Empty<FirebaseObject<T>>();
                 }
 
                 return dictionary.Select(item => new FirebaseObject<T>(item.Key, item.Value)).ToList();

src/Firebase/Offline/DatabaseExtensions.cs

@@ -13,6 +13,7 @@ public static class DatabaseExtensions
         /// Create new instances of the <see cref="RealtimeDatabase{T}"/>.
         /// </summary>
         /// <typeparam name="T"> Type of elements. </typeparam>
+        /// <param name="query"> The child query. </param>
         /// <param name="filenameModifier"> Custom string which will get appended to the file name. </param>
         /// <param name="elementRoot"> Optional custom root element of received json items. </param>
         /// <param name="streamingOptions"> Realtime streaming options. </param> 
@@ -30,6 +31,7 @@ public static RealtimeDatabase<T> AsRealtimeDatabase<T>(this ChildQuery query, s
         /// </summary>
         /// <typeparam name="T"> Type of elements. </typeparam>
         /// <typeparam name="TSetHandler"> Type of the custom <see cref="ISetHandler{T}"/> to use. </typeparam>
+        /// <param name="query"> The child query. </param>
         /// <param name="filenameModifier"> Custom string which will get appended to the file name. </param>
         /// <param name="elementRoot"> Optional custom root element of received json items. </param>
         /// <param name="streamingOptions"> Realtime streaming options. </param> 
@@ -46,6 +48,7 @@ public static RealtimeDatabase<T> AsRealtimeDatabase<T, TSetHandler>(this ChildQ
         /// <summary>
         /// Overwrites existing object with given key leaving any missing properties intact in firebase.
         /// </summary>
+        /// <param name="db"> Database instance. </param>
         /// <param name="key"> The key. </param>
         /// <param name="obj"> The object to set. </param>
         /// <param name="syncOnline"> Indicates whether the item should be synced online. </param>
@@ -59,6 +62,7 @@ public static void Patch<T>(this RealtimeDatabase<T> db, string key, T obj, bool
         /// <summary>
         /// Overwrites existing object with given key.
         /// </summary>
+        /// <param name="db"> Database instance. </param>
         /// <param name="key"> The key. </param>
         /// <param name="obj"> The object to set. </param>
         /// <param name="syncOnline"> Indicates whether the item should be synced online. </param>
@@ -72,6 +76,7 @@ public static void Put<T>(this RealtimeDatabase<T> db, string key, T obj, bool s
         /// <summary>
         /// Adds a new entity to the Database.
         /// </summary>
+        /// <param name="db"> Database instance. </param>
         /// <param name="obj"> The object to add.  </param>
         /// <param name="syncOnline"> Indicates whether the item should be synced online. </param>
         /// <param name="priority"> The priority. Objects with higher priority will be synced first. Higher number indicates higher priority. </param>
@@ -89,6 +94,7 @@ public static string Post<T>(this RealtimeDatabase<T> db, T obj, bool syncOnline
         /// <summary>
         /// Deletes the entity with the given key.
         /// </summary>
+        /// <param name="db"> Database instance. </param>
         /// <param name="key"> The key. </param>
         /// <param name="syncOnline"> Indicates whether the item should be synced online. </param>
         /// <param name="priority"> The priority. Objects with higher priority will be synced first. Higher number indicates higher priority. </param> 
@@ -140,7 +146,6 @@ public static void Patch<T, TProperty>(this RealtimeDatabase<T> db, string key,
         /// <param name="db"> Database instance. </param>
         /// <param name="key"> Key of the root element to modify. </param>
         /// <param name="propertyExpression"> Expression on the root element leading to target value to modify. </param>
-        /// <param name="value"> Value to put. </param>
         /// <param name="syncOnline"> Indicates whether the item should be synced online. </param>
         /// <param name="priority"> The priority. Objects with higher priority will be synced first. Higher number indicates higher priority. </param> 
         public static void Delete<T, TProperty>(this RealtimeDatabase<T> db, string key, Expression<Func<T, TProperty>> propertyExpression, bool syncOnline = true, int priority = 1)
@@ -177,7 +182,6 @@ public static void Post<T, TSelector, TProperty>(this RealtimeDatabase<T> db, st
         /// The key of the new entity is automatically generated.
         /// </summary>
         /// <typeparam name="T"> Type of the root elements. </typeparam>
-        /// <typeparam name="TSelector"> Type of the dictionary being modified</typeparam>
         /// <typeparam name="TProperty"> Type of the value within the dictionary being modified</typeparam>
         /// <param name="db"> Database instance. </param>
         /// <param name="key"> Key of the root element to modify. </param>

src/Firebase/Offline/OfflineEntry.cs

@@ -16,8 +16,10 @@ public class OfflineEntry
         /// </summary>
         /// <param name="key"> The key. </param>
         /// <param name="obj"> The object. </param>
-        /// <param name="priority"> The priority. Objects with higher priority will be synced first. Higher number indicates higher priority. </param>  
+        /// <param name="data"> The json data. </param>
+        /// <param name="priority"> The priority. Objects with higher priority will be synced first. Higher number indicates higher priority. </param>
         /// <param name="syncOptions"> The sync options. </param>
+        /// <param name="isPartial"> A value indicating whether this is only a partial object. </param>
         public OfflineEntry(string key, object obj, string data, int priority, SyncOptions syncOptions, bool isPartial = false)
         {
             this.Key = key;
@@ -37,6 +39,7 @@ public OfflineEntry(string key, object obj, string data, int priority, SyncOptio
         /// <param name="obj"> The object. </param>
         /// <param name="priority"> The priority. Objects with higher priority will be synced first. Higher number indicates higher priority. </param>  
         /// <param name="syncOptions"> The sync options. </param>
+        /// <param name="isPartial"> A value indicating whether this is only a partial object. </param>
         public OfflineEntry(string key, object obj, int priority, SyncOptions syncOptions, bool isPartial = false)
             : this(key, obj, JsonConvert.SerializeObject(obj), priority, syncOptions, isPartial)
         {

src/Firebase/Offline/RealtimeDatabase.cs

@@ -43,9 +43,10 @@ public partial class RealtimeDatabase<T> : IDisposable where T : class
         /// <param name="elementRoot"> The element Root. </param>
         /// <param name="offlineDatabaseFactory"> The offline database factory.  </param>
         /// <param name="filenameModifier"> Custom string which will get appended to the file name.  </param>
-        /// <param name="streamChanges"> Specifies whether changes should be streamed from the server.  </param>
-        /// <param name="pullEverythingOnStart"> Specifies if everything should be pull from the online storage on start. It only makes sense when <see cref="streamChanges"/> is set to true. </param>
+        /// <param name="streamingOptions"> Specifies condition for which items get streamed. </param>
+        /// <param name="initialPullStrategy"> Specifies the strategy for initial pull of server data. </param>
         /// <param name="pushChanges"> Specifies whether changed items should actually be pushed to the server. If this is false, then Put / Post / Delete will not affect server data. </param>
+        /// <param name="setHandler"></param>
         public RealtimeDatabase(ChildQuery childQuery, string elementRoot, Func<Type, string, IDictionary<string, OfflineEntry>> offlineDatabaseFactory, string filenameModifier, StreamingOptions streamingOptions, InitialPullStrategy initialPullStrategy, bool pushChanges, ISetHandler<T> setHandler = null)
         {
             this.childQuery = childQuery;
@@ -93,7 +94,7 @@ public ISetHandler<T> PutHandler
         /// </summary>
         /// <param name="key"> The key. </param>
         /// <param name="obj"> The object to set. </param>
-        /// <param name="syncOnline"> Indicates whether the item should be synced online. </param>
+        /// <param name="syncOptions"> Specifies type of sync requested for given data. </param>
         /// <param name="priority"> The priority. Objects with higher priority will be synced first. Higher number indicates higher priority. </param>
         public void Set(string key, T obj, SyncOptions syncOptions, int priority = 1)
         {
@@ -293,7 +294,7 @@ private IObservable<IReadOnlyCollection<FirebaseObject<T>>> GetInitialPullObserv
             }
 
             // there is an element root, which indicates the target location is not a collection but a single element
-            return Observable.Defer(async () => Observable.Return(await query.OnceSingleAsync<T>()).Select(e => new[] { new FirebaseObject<T>(this.elementRoot, e) }));
+            return Observable.Defer(async () => Observable.Return(await query.OnceSingleAsync<T>().ConfigureAwait(false)).Select(e => new[] { new FirebaseObject<T>(this.elementRoot, e) }));
         }
 
         private IDisposable InitializeStreamingSubscription(IObserver<FirebaseEvent<T>> observer)
@@ -336,19 +337,19 @@ private async void SynchronizeThread()
                 try
                 {
                     var validEntries = this.Database.Where(e => e.Value != null);
-                    await this.PullEntriesAsync(validEntries.Where(kvp => kvp.Value.SyncOptions == SyncOptions.Pull));
+                    await PullEntriesAsync(validEntries.Where(kvp => kvp.Value.SyncOptions == SyncOptions.Pull)).ConfigureAwait(false);
 
                     if (this.pushChanges)
                     {
-                        await this.PushEntriesAsync(validEntries.Where(kvp => kvp.Value.SyncOptions == SyncOptions.Put || kvp.Value.SyncOptions == SyncOptions.Patch));
+                        await PushEntriesAsync(validEntries.Where(kvp => kvp.Value.SyncOptions == SyncOptions.Put || kvp.Value.SyncOptions == SyncOptions.Patch)).ConfigureAwait(false);
                     }
                 }
                 catch (Exception ex)
                 {
                     this.SyncExceptionThrown?.Invoke(this, new ExceptionEventArgs(ex));
                 }
 
-                await Task.Delay(this.childQuery.Client.Options.SyncPeriod);
+                await Task.Delay(childQuery.Client.Options.SyncPeriod).ConfigureAwait(false);
             }
         }
 
@@ -377,7 +378,7 @@ private async Task PushEntriesAsync(IEnumerable<KeyValuePair<string, OfflineEntr
 
                 try
                 {
-                    await Task.WhenAll(tasks).WithAggregateException();
+                    await Task.WhenAll(tasks).WithAggregateException().ConfigureAwait(false);
                 }
                 catch (Exception ex)
                 {
@@ -396,7 +397,7 @@ private async Task PullEntriesAsync(IEnumerable<KeyValuePair<string, OfflineEntr
 
                 try
                 { 
-                    await Task.WhenAll(tasks).WithAggregateException();
+                    await Task.WhenAll(tasks).WithAggregateException().ConfigureAwait(false);
                 }
                 catch (Exception ex)
                 {
@@ -407,13 +408,13 @@ private async Task PullEntriesAsync(IEnumerable<KeyValuePair<string, OfflineEntr
 
         private async Task ResetAfterPull(Task<T> task, string key, OfflineEntry entry)
         {
-            await task;
+            await task.ConfigureAwait(false);
             this.SetAndRaise(key, new OfflineEntry(key, task.Result, entry.Priority, SyncOptions.None), FirebaseEventSource.OnlinePull);
         }
 
         private async Task ResetSyncAfterPush(Task task, string key, T obj)
         {
-            await this.ResetSyncAfterPush(task, key);
+            await ResetSyncAfterPush(task, key).ConfigureAwait(false);
 
             if (this.streamingOptions == StreamingOptions.None)
             {
@@ -423,7 +424,7 @@ private async Task ResetSyncAfterPush(Task task, string key, T obj)
 
         private async Task ResetSyncAfterPush(Task task, string key)
         {
-            await task;
+            await task.ConfigureAwait(false);
             this.ResetSyncOptions(key);
         }
 

src/Firebase/Offline/SetHandler.cs

@@ -6,17 +6,18 @@
 
     public class SetHandler<T> : ISetHandler<T>
     {
-        public virtual async Task SetAsync(ChildQuery query, string key, OfflineEntry entry)
+        public virtual Task SetAsync(ChildQuery query, string key, OfflineEntry entry)
         {
             using (var child = query.Child(key))
             {
                 if (entry.SyncOptions == SyncOptions.Put)
                 {
-                    await child.PutAsync(entry.Data);
+                    return child.PutAsync(entry.Data);
                 }
                 else
                 {
-                    await child.PatchAsync(entry.Data);
+                    
+                    return child.PatchAsync(entry.Data);
                 }
             }
         }

src/Firebase/Query/FirebaseQuery.cs

@@ -109,6 +109,7 @@ public async Task<T> OnceSingleAsync<T>(TimeSpan? timeout = null)
         /// Starts observing this query watching for changes real time sent by the server.
         /// </summary>
         /// <typeparam name="T"> Type of elements. </typeparam>
+        /// <param name="exceptionHandler"> Optional exception handler for the stream subscription. </param>
         /// <param name="elementRoot"> Optional custom root element of received json items. </param>
         /// <returns> Observable stream of <see cref="FirebaseEvent{T}"/>. </returns>
         public IObservable<FirebaseEvent<T>> AsObservable<T>(EventHandler<ContinueExceptionEventArgs<FirebaseException>> exceptionHandler = null, string elementRoot = "")
@@ -140,10 +141,9 @@ public async Task<string> BuildUrlAsync()
         /// <summary>
         /// Posts given object to repository.
         /// </summary>
-        /// <param name="obj"> The object. </param>
+        /// <param name="data"> The json data. </param>
         /// <param name="generateKeyOffline"> Specifies whether the key should be generated offline instead of online. </param>
         /// <param name="timeout"> Optional timeout value. </param>
-        /// <typeparam name="T"> Type of <see cref="obj"/> </typeparam>
         /// <returns> Resulting firebase object with populated key. </returns>
         public async Task<FirebaseObject<string>> PostAsync(string data, bool generateKeyOffline = true, TimeSpan? timeout = null)
         {
@@ -168,29 +168,27 @@ public async Task<FirebaseObject<string>> PostAsync(string data, bool generateKe
         /// <summary>
         /// Patches data at given location instead of overwriting them.
         /// </summary> 
-        /// <param name="obj"> The object. </param>
+        /// <param name="data"> The json data. </param>
         /// <param name="timeout"> Optional timeout value. </param>
-        /// <typeparam name="T"> Type of <see cref="obj"/> </typeparam>
         /// <returns> The <see cref="Task"/>. </returns>
-        public async Task PatchAsync(string data, TimeSpan? timeout = null)
+        public Task PatchAsync(string data, TimeSpan? timeout = null)
         {
             var c = this.GetClient(timeout);
 
-            await this.Silent().SendAsync(c, data, new HttpMethod("PATCH")).ConfigureAwait(false);
+            return this.Silent().SendAsync(c, data, new HttpMethod("PATCH"));
         }
 
         /// <summary>
         /// Sets or overwrites data at given location.
         /// </summary> 
-        /// <param name="obj"> The object. </param>
+        /// <param name="data"> The json data. </param>
         /// <param name="timeout"> Optional timeout value. </param>
-        /// <typeparam name="T"> Type of <see cref="obj"/> </typeparam>
         /// <returns> The <see cref="Task"/>. </returns>
-        public async Task PutAsync(string data, TimeSpan? timeout = null)
+        public Task PutAsync(string data, TimeSpan? timeout = null)
         {
             var c = this.GetClient(timeout);
 
-            await this.Silent().SendAsync(c, data, HttpMethod.Put).ConfigureAwait(false);
+            return this.Silent().SendAsync(c, data, HttpMethod.Put);
         }
 
         /// <summary>