Add core classes documentation (#44)

## What does this PR do ?

I didn't use the new documentation format we decide in the product workshop (third level of sub menu with Properties and Methods) because the documentation framework can't handle it for now. 

The properties are listed in the class description (eg: [Kuzzle](https://deploy-preview-44--doc-sdk-csharp.netlify.com/core-classes/kuzzle/introduction/))

Add core classes documentation:
 - [Kuzzle](https://deploy-preview-44--doc-sdk-csharp.netlify.com/core-classes/kuzzle/introduction/)
 - [KuzzleEventHandler](https://deploy-preview-44--doc-sdk-csharp.netlify.com/core-classes/kuzzle-event-handler/)
 - [Response](https://deploy-preview-44--doc-sdk-csharp.netlify.com/core-classes/response/)
 - [SearchResults](https://deploy-preview-44--doc-sdk-csharp.netlify.com/core-classes/search-results/)
 - [SearchOptions](https://deploy-preview-44--doc-sdk-csharp.netlify.com/core-classes/search-options/)
 - [SubscribeOptions](https://deploy-preview-44--doc-sdk-csharp.netlify.com/core-classes/subscribe-options/)
 - [WebSocket](https://deploy-preview-44--doc-sdk-csharp.netlify.com/protocols/websocket/introduction/)

Add essentials documentation:
 - [Events](https://deploy-preview-44--doc-sdk-csharp.netlify.com/essentials/events/)
 - [Realtime Notifications](https://deploy-preview-44--doc-sdk-csharp.netlify.com/essentials/realtime-notifications/)

### Other changes
 - SearchOptions accept the `Sort` param
 - remove obsolete `Kuzzle.Jwt` property

Author: Aschen

.ci/doc/templates/default.tpl.cs

@@ -12,6 +12,7 @@
 using KuzzleSdk.Exceptions;
 using KuzzleSdk.API.Options;
 using KuzzleSdk.API.DataObjects;
+using KuzzleSdk.API;
 
 WebSocket socket = new WebSocket(new Uri("ws://kuzzle:7512"));
 KuzzleSdk.Kuzzle kuzzle = new KuzzleSdk.Kuzzle(socket);

.ci/doc/templates/empty.tpl.cs

@@ -0,0 +1,8 @@
+#r "Kuzzle.dll"
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+
+[snippet-code]
+
+Console.WriteLine("Success");

.ci/doc/templates/without-connect.tpl.cs

@@ -0,0 +1,16 @@
+#r "Kuzzle.dll"
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+using KuzzleSdk;
+using KuzzleSdk.Protocol;
+using Newtonsoft.Json.Linq;
+
+WebSocket socket = new WebSocket(new Uri("ws://kuzzle:7512"));
+KuzzleSdk.Kuzzle kuzzle = new KuzzleSdk.Kuzzle(socket);
+
+kuzzle.ConnectAsync(CancellationToken.None).Wait();
+
+[snippet-code]
+
+Console.WriteLine("Success");

Kuzzle/API/DataObjects/SearchResults.cs

@@ -8,7 +8,7 @@ namespace KuzzleSdk.API.DataObjects {
   /// </summary>
   public class SearchResults {
     /// <summary>
-    /// Kuzzle instance 
+    /// Kuzzle instance
     /// </summary>
     protected readonly IKuzzleApi api;
 
@@ -23,7 +23,7 @@ public class SearchResults {
     protected readonly JObject request;
 
     /// <summary>
-    /// To be overloaded by specialized SearchResult children
+    /// To be overloaded by specialized SearchResults children
     /// </summary>
     protected readonly string scrollAction = "scroll";
 
@@ -86,14 +86,16 @@ private JObject GetSearchAfterRequest() {
 
         if (value.Type == JTokenType.String) {
           key = (string)value;
-        } else {
+        }
+        else {
           key = (string)((JObject)value).First;
         }
 
         if (key == "_uid") {
           searchAfter.Add((string)request["collection"] + "#"
             + (string)lastItem["_id"]);
-        } else {
+        }
+        else {
           searchAfter.Add(lastItem["_source"].SelectToken(key));
         }
       }
@@ -102,7 +104,7 @@ private JObject GetSearchAfterRequest() {
     }
 
     /// <summary>
-    /// Returns a new SearchResult object which contain the subsequent results 
+    /// Returns a new SearchResults object which contain the subsequent results
     /// of the search.
     /// </summary>
     public async Task<SearchResults> NextAsync() {
@@ -112,13 +114,15 @@ public async Task<SearchResults> NextAsync() {
 
       if (ScrollId != null) {
         nextRequest = GetScrollRequest();
-      } else if (
+      }
+      else if (
         options.Size != null &&
         request["body"]["sort"] != null &&
         request["body"]["sort"].Type != JTokenType.Null
       ) {
         nextRequest = GetSearchAfterRequest();
-      } else if (options.Size != null) {
+      }
+      else if (options.Size != null) {
         if (options.From != null && options.From > Total) {
           return null;
         }

Kuzzle/API/Options/SearchOptions.cs

@@ -37,6 +37,17 @@ public class SearchOptions {
     ]
     public string Scroll { get; set; }
 
+    /// <summary>
+    /// Field to sort the result on
+    /// </summary>
+    [
+      JsonProperty(
+        PropertyName = "sort",
+        NullValueHandling = NullValueHandling.Ignore
+      )
+    ]
+    public string Sort { get; set; }
+
     /// <summary>
     /// Copy constructor.
     /// </summary>
@@ -45,14 +56,18 @@ public SearchOptions(SearchOptions src) {
         From = src.From;
         Size = src.Size;
 
+        if (src.Sort != null) {
+          Sort = string.Copy(src.Sort);
+        }
+
         if (src.Scroll != null) {
           Scroll = string.Copy(src.Scroll);
         }
       }
     }
 
     /// <summary>
-    /// Initializes a new instance of the 
+    /// Initializes a new instance of the
     /// <see cref="T:KuzzleSdk.API.Options.SearchOptions"/> class.
     /// </summary>
     public SearchOptions() { }

Kuzzle/EventHandler/KuzzleEventHandler.cs

@@ -1,40 +1,40 @@
 using System;
-using System.ComponentModel;
-using KuzzleSdk.API;
-using KuzzleSdk.EventHandler.Events;
-
-namespace KuzzleSdk.EventHandler {
+using System.ComponentModel;
+using KuzzleSdk.API;
+using KuzzleSdk.EventHandler.Events;
+
+namespace KuzzleSdk.EventHandler {
   public sealed class KuzzleEventHandler : AbstractKuzzleEventHandler {
 
     private IKuzzleApi kuzzle;
-
+
     public KuzzleEventHandler(IKuzzleApi kuzzle) {
-      this.kuzzle = kuzzle;
-    }
-
-    private EventHandlerList eventHandlerList = new EventHandlerList();
-
-    private static readonly object subscriptionEventKey = new object();       // Internal
+      this.kuzzle = kuzzle;
+    }
+
+    private EventHandlerList eventHandlerList = new EventHandlerList();
+
+    private static readonly object subscriptionEventKey = new object();       // Internal
     private static readonly object userLoggedInEventKey = new object();       // Internal
-    private static readonly object userLoggedOutEventKey = new object();      // Internal
-    private static readonly object reconnectedEventKey = new object();        // Public
-    private static readonly object queueRecoveredEventKey = new object();     // Public
+    private static readonly object userLoggedOutEventKey = new object();      // Internal
+    private static readonly object reconnectedEventKey = new object();        // Public
+    private static readonly object queueRecoveredEventKey = new object();     // Public
     private static readonly object unhandledResponseEventKey = new object();  // Public
-    private static readonly object tokenExpiredEventKey = new object();       // Public
-
+    private static readonly object tokenExpiredEventKey = new object();       // Public
+
     /// <summary>
     /// Occurs when we have to [add, remove, clear] subscriptions :
-    /// </summary>
-    public override event EventHandler<SubscriptionEvent> Subscription {
-      add {
-        eventHandlerList.AddHandler(subscriptionEventKey, value);
+    /// </summary>
+    public override event EventHandler<SubscriptionEvent> Subscription {
+      add {
+        eventHandlerList.AddHandler(subscriptionEventKey, value);
       }
 
       remove {
         eventHandlerList.RemoveHandler(subscriptionEventKey, value);
-      }
-    }
-
+      }
+    }
+
     internal override void DispatchSubscription(SubscriptionEvent subscriptionData) {
       EventHandler<SubscriptionEvent> subscriptionEvent =
       (EventHandler<SubscriptionEvent>)eventHandlerList[subscriptionEventKey];
@@ -53,18 +53,18 @@ public override event EventHandler<UserLoggedInEvent> UserLoggedIn {
       remove {
         eventHandlerList.RemoveHandler(userLoggedInEventKey, value);
       }
-    }
-
+    }
+
     internal override void DispatchUserLoggedIn(string kuid) {
       EventHandler<UserLoggedInEvent> userLoggedIn =
       (EventHandler<UserLoggedInEvent>)eventHandlerList[userLoggedInEventKey];
 
       userLoggedIn?.Invoke(this, new UserLoggedInEvent(kuid));
-    }
+    }
 
     /// <summary>
     /// Occurs when the successfuly reconnected to the network
-    /// </summary>
+    /// </summary>
     public override event Action Reconnected {
       add {
         eventHandlerList.AddHandler(reconnectedEventKey, value);
@@ -73,16 +73,16 @@ public override event Action Reconnected {
       remove {
         eventHandlerList.RemoveHandler(reconnectedEventKey, value);
       }
-    }
-
+    }
+
     internal override void DispatchReconnected() {
       Action queueRecovered = (Action)eventHandlerList[reconnectedEventKey];
       queueRecovered?.Invoke();
-    }
+    }
 
     /// <summary>
     /// Occurs when the offline queue of query has been successfuly recovered
-    /// </summary>
+    /// </summary>
     public override event Action QueueRecovered {
       add {
         eventHandlerList.AddHandler(queueRecoveredEventKey, value);
@@ -91,8 +91,8 @@ public override event Action QueueRecovered {
       remove {
         eventHandlerList.RemoveHandler(queueRecoveredEventKey, value);
       }
-    }
-
+    }
+
     internal override void DispatchQueueRecovered() {
       Action queueRecovered = (Action)eventHandlerList[queueRecoveredEventKey];
       queueRecovered?.Invoke();
@@ -101,42 +101,45 @@ internal override void DispatchQueueRecovered() {
     /// <summary>
     /// Occurs when an unhandled response is received.
     /// </summary>
-    public override event EventHandler<Response> UnhandledResponse {
+    public override event EventHandler<Response> UnhandledResponse {
       add {
         eventHandlerList.AddHandler(unhandledResponseEventKey, value);
       }
 
       remove {
         eventHandlerList.RemoveHandler(unhandledResponseEventKey, value);
-      }
+      }
     }
 
     internal override void DispatchUnhandledResponse(Response response) {
       EventHandler<Response> unhandledResponse =
       (EventHandler<Response>)eventHandlerList[unhandledResponseEventKey];
 
-      unhandledResponse?.Invoke(this, response);
-    }
-
+      unhandledResponse?.Invoke(this, response);
+    }
+
     /// <summary>
-    /// Token expiration event 
+    /// Token expiration event
     /// </summary>
-    public override event Action TokenExpired {
+    public override event Action TokenExpired {
       add {
         eventHandlerList.AddHandler(tokenExpiredEventKey, value);
       }
 
       remove {
         eventHandlerList.RemoveHandler(tokenExpiredEventKey, value);
-      }
-    }
-
+      }
+    }
+
     internal override void DispatchTokenExpired() {
       kuzzle.AuthenticationToken = null;
       Action tokenExpired = (Action)eventHandlerList[tokenExpiredEventKey];
       tokenExpired?.Invoke();
-    }
+    }
 
+    /// <summary>
+    /// Occurs when a user has logged out.
+    /// </summary>
     public override event Action UserLoggedOut {
       add {
         eventHandlerList.AddHandler(userLoggedOutEventKey, value);
@@ -146,10 +149,10 @@ public override event Action UserLoggedOut {
         eventHandlerList.RemoveHandler(userLoggedOutEventKey, value);
       }
     }
-
-    internal override void DispatchUserLoggedOut() {
+
+    internal override void DispatchUserLoggedOut() {
       Action userLoggedOut = (Action)eventHandlerList[userLoggedOutEventKey];
-      userLoggedOut?.Invoke();
-    }
-  }
-}
+      userLoggedOut?.Invoke();
+    }
+  }
+}

Kuzzle/Kuzzle.cs

@@ -195,16 +195,6 @@ public bool AutoRecover {
     /// </summary>
     public string AuthenticationToken { get; set; }
 
-    /// <summary>
-    /// Authentication token (deprecated, use AuthenticationToken instead)
-    /// </summary>
-    [Obsolete(
-      "The Jwt property is deprecated, use AuthencationToken instead", false)]
-    string Jwt {
-      get { return AuthenticationToken; }
-      set { AuthenticationToken = value; }
-    }
-
     /// <summary>
     /// Network Protocol
     /// </summary>
@@ -279,7 +269,8 @@ public Kuzzle(
       int minTokenDuration = 3600000,
       int maxQueueSize = -1,
       int maxRequestDelay = 1000,
-      Func<JObject, bool> queueFiler = null
+      bool autoRecover = false,
+      Func<JObject, bool> queueFilter = null
     ) {
       NetworkProtocol = networkProtocol;
       NetworkProtocol.ResponseEvent += ResponsesListener;
@@ -302,7 +293,8 @@ public Kuzzle(
         MinTokenDuration = minTokenDuration,
         MaxQueueSize = maxQueueSize,
         MaxRequestDelay = maxRequestDelay,
-        QueueFilter = queueFiler
+        QueueFilter = queueFilter,
+        AutoRecover = autoRecover
       };
 
       // Initializes instance unique properties

doc/2/controllers/auth/check-token/index.md

@@ -2,12 +2,12 @@
 code: true
 type: page
 title: CheckTokenAsync
-description: Checks a JWT Token's validity.
+description: Checks an authentication Token's validity.
 ---
 
 # CheckTokenAsync
 
-Checks a JWT Token's validity.
+Checks an authentication token's validity.
 
 ## Arguments
 
@@ -17,7 +17,7 @@ public async Task<JObject> CheckTokenAsync(string token);
 
 | Argument | Type              | Description |
 |----------|-------------------|-------------|
-| `token`  | <pre>string</pre> | JWT token   |
+| `token`  | <pre>string</pre> | Authentication token   |
 
 ## Return
 

doc/2/controllers/auth/check-token/snippets/check-token.test.yml

@@ -1,5 +1,5 @@
 name: Auth#CheckTokenAsync
-description: Checks a JWT Token's validity.
+description: Checks an authentication token's validity.
 hooks:
   before: curl -X POST kuzzle:7512/users/foo/_create -H "Content-Type:application/json" --data '{"content":{"profileIds":["default"]},"credentials":{"local":{"username":"foo","password":"bar"}}}'
   after: curl -X DELETE kuzzle:7512/users/foo