JS SDK: document class properties independently to the "introduction" pages (#277)

* [JS SDK] separate class properties from the "introduction" page

* [JS SDK] document what the auth actions do to the jwt class property

* Apply @xbill82's suggestions

Co-Authored-By: scottinet <[email protected]>

Author: scottinet

src/sdk-reference/js/6/auth/login/index.md

@@ -8,7 +8,9 @@ description: Authenticate a user
 
 Authenticates a user.
 
-If this action is successful, all further requests emitted by this SDK instance will be in the name of the authenticated user, until either the authenticated token expires, the [logout]({{ site_base_path }}sdk-reference/js/6/auth/logout) action is called, or the [jwt]({{ site_base_path }}sdk-reference/js/6/kuzzle/introduction/#properties) property is manually unset.
+If this action is successful, then the [jwt]({{ site_base_path }}sdk-reference/js/6/kuzzle/properties) property of this class instance is set to the new authentication token.
+
+All further requests emitted by this SDK instance will be on behalf of the authenticated user, until either the authenticated token expires, the [logout]({{ site_base_path }}sdk-reference/js/6/auth/logout) action is called, or the `jwt` property is manually set to another value.
 
 ## Arguments
 

src/sdk-reference/js/6/auth/logout/index.md

@@ -6,11 +6,13 @@ description: Revokes the user's token & unsubscribe them from registered rooms.
 
 # logout
 
-Revokes the user's authentication token.
+Revokes the current authentication token.
 
 If there were any, real-time subscriptions are cancelled.
 
-<br/>
+If this action is successful, then the [jwt]({{ site_base_path }}sdk-reference/js/6/kuzzle/properties) property of this class instance is unset.
+
+## Arguments
 
 ```javascript
 logout ()

src/sdk-reference/js/6/auth/refresh-token/index.md

@@ -10,7 +10,10 @@ description: Refresh an authentication token
 
 Refreshes a valid, non-expired authentication token.
 
-If this action is successful, all further requests emitted by this SDK instance will use the refreshed authentication token.
+If this action is successful, then the [jwt]({{ site_base_path }}sdk-reference/js/6/kuzzle/properties) property of this class instance is set to the new authentication token.
+
+All further requests emitted by this SDK instance will be on behalf of the authenticated user, until either the authenticated token expires, the [logout]({{ site_base_path }}sdk-reference/js/6/auth/logout) action is called, or the `jwt` property is manually set to another value.
+
 
 ## Arguments
 

src/sdk-reference/js/6/kuzzle-error/introduction/index.md

@@ -10,13 +10,3 @@ order: 0
 Inherits from the standard `Error` class.
 
 The KuzzleError class represents an [error response from Kuzzle API]({{ site_base_path }}api/1/essentials/errors/).
-
-## Properties
-
-Available properties.
-
-| Property name        | Type     | Description          |
-| -------------------- | -------- | --------------------------------------- |
-| `message`            | <pre>string</pre> | Error message    |
-| `status`             | <pre>number</pre> | Error status code      |
-| `stack`              | <pre>string</pre> | Error stacktrace (only in development mode)   |

src/sdk-reference/js/6/kuzzle-error/properties/index.md

@@ -0,0 +1,13 @@
+---
+layout: sdk.html.hbs
+title: Properties
+description: KuzzleError Properties
+---
+
+# Properties
+
+| Property name        | Type     | Description          |
+| -------------------- | -------- | --------------------------------------- |
+| `message`            | <pre>string</pre> | Error message    |
+| `status`             | <pre>number</pre> | Error status code      |
+| `stack`              | <pre>string</pre> | Error stacktrace (only in development mode)   |

src/sdk-reference/js/6/kuzzle/introduction/index.md

@@ -32,70 +32,3 @@ The following protocols are available in the SDK JS 6:
 You can tell the Kuzzle SDK to attach a set of "volatile" data to each request. You can set it as an object contained in the `volatile` field of the Kuzzle constructor. The response to a request containing volatile data will contain the same data in its `volatile` field. This can be useful, for example, in real-time notifications for [user join/leave notifications]({{site_base_path}}api/1/essentials/volatile-data/) to provide additional informations about the client who sent the request.
 
 Note that you can also set volatile data on a per-request basis (on requests that accept a `volatile` field in their `options` argument). In this case, per-request volatile data will be merged with the global `volatile` object set in the constructor. Per-request fields will override global ones.
-
-## Properties
-
-Available properties.
-
-| Property name        | Type     | Description          | Writable? |
-| -------------------- | -------- | --------------------------------------- | :-------: |
-| `autoQueue`          | <pre>boolean</pre> | Automatically queue all requests during offline mode    |    Yes    |
-| `autoReplay`         | <pre>boolean</pre> | Automatically replay queued requests on a `reconnected` event        |    Yes    |
-| `autoResubscribe`    | <pre>boolean</pre> | Automatically renew all subscriptions on a `reconnected` event       |    Yes    |
-| `jwt`                | <pre>string</pre> | Token used in requests for authentication        |    Yes    |
-| `offlineQueue`       | <pre>object[]</pre> | Contains the queued requests during offline mode   |    No     |
-| `offlineQueueLoader` | <pre>function</pre> | Called before dequeuing requests after exiting offline mode,</br> to add items at the beginning of the offline queue  |    Yes    |
-| `protocol`       | <pre>Protocol</pre> | Protocol used by the SDK   |    No     |
-| `queueFilter`        | <pre>function</pre> | Called during offline mode. </br>Takes a request object as arguments and returns a boolean, indicating if a request can be queued |    Yes    |
-| `queueMaxSize`       | <pre>number</pre>  | Number of maximum requests kept during offline mode|    Yes    |
-| `queueTTL`           | <pre>number</pre>  | Time a queued request is kept during offline mode, in milliseconds      |    Yes    |
-| `replayInterval`     | <pre>number</pre>  | Delay between each replayed requests               |    Yes    |
-| `volatile`           | <pre>object</pre> | Common volatile data, will be sent to all future requests       |    Yes    |
-
-### offlineQueueLoader
-
-The `offlineQueueLoader` property must be set with a function of one of the following formats:
-
-```js
-Object[] offlineQueueLoader()
-
-Promise<Object[]> offlineQueueLoader()
-```
-
-The returned (or resolved) array must contain objects, each with the following properties:
-
-| Property | Type | Description |
-|---|---|---|
-| `query` | <pre>object</pre> | Object representing the request that is about to be sent to Kuzzle, following the [Kuzzle API]({{ site_base_path }}api/1/essentials/query-syntax) format |
-| `reject` | <pre>function</pre> | A [Promise.reject](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/reject) function |
-| `resolve` | <pre>function</pre> | A [Promise.resolve](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/resolve) function |
-
-### queueFilter
-
-The `queueFilter` property must be set with a function of the following form:
-
-```js
-boolean queueFilter(request)
-```
-
-The `request` argument is an object representing the request that is about to be sent to Kuzzle, following the [Kuzzle API]({{ site_base_path }}api/1/essentials/query-syntax) format.
-
-### queueMaxSize
-
-This property defines the size of the offline buffer, which is a first-in first-out (FIFO) queue.
-
-This means that if the `queueMaxSize` limit is reached, older requests are discarded to make room for newer requests.
-
-If `queueMaxSize` is set to a number lower than, or equal to `0`, then an unlimited number of requests is kept in the offline buffer.  
-Note that doing so may lead to a crash due to memory saturation, if there are too many requests held in memory.
-
-### queueTTL
-
-If the `queueTTL` property is set to a number lower than, or equal to `0`, then requests never expire and are kept indefinitely.
-
-### volatile
-
-Multiple methods allow passing specific `volatile` data. 
-
-These `volatile` data will be merged with the global Kuzzle `volatile` object when sending the request, with the request specific `volatile` taking priority over the global ones.
-

src/sdk-reference/js/6/kuzzle/properties/index.md

@@ -0,0 +1,76 @@
+---
+layout: sdk.html.hbs
+title: Properties
+description: Kuzzle class properties
+order: 100
+---
+
+# Read-only properties
+
+| Property name        | Type     | Description          |
+| -------------------- | -------- | ---------------------|
+| `offlineQueue` | <pre>object[]</pre> | Contains the queued requests during offline mode   |
+| `protocol` | <pre>Protocol</pre> | Protocol used by the SDK |
+
+# Writable properties
+
+| Property name        | Type     | Description          |
+| -------------------- | -------- | ---------------------|
+| `autoQueue` | <pre>boolean</pre> | If `true`, automatically queues all requests during offline mode |
+| `autoReplay` | <pre>boolean</pre> | If `true`, automatically replays queued requests on a `reconnected` event |
+| `autoResubscribe` | <pre>boolean</pre> | If `true`, automatically renews all subscriptions on a `reconnected` event |
+| `jwt` | <pre>string</pre> | Authentication token |
+| `offlineQueueLoader` | <pre>function</pre> | Called before dequeuing requests after exiting offline mode, to add items at the beginning of the offline queue  |
+| `queueFilter` | <pre>function</pre> | Custom function called during offline mode to filter queued requests on-the-fly |
+| `queueMaxSize` | <pre>number</pre>  | Number of maximum requests kept during offline mode|
+| `queueTTL` | <pre>number</pre>  | Time a queued request is kept during offline mode, in milliseconds |
+| `replayInterval` | <pre>number</pre>  | Delay between each replayed requests |
+| `volatile` | <pre>object</pre> | Common volatile data, will be sent to all future requests |
+
+### offlineQueueLoader
+
+The `offlineQueueLoader` property must be set with a function of one of the following formats:
+
+```js
+Object[] offlineQueueLoader()
+
+Promise<Object[]> offlineQueueLoader()
+```
+
+The returned (or resolved) array must contain objects, each with the following properties:
+
+| Property | Type | Description |
+|---|---|---|
+| `query` | <pre>object</pre> | Object representing the request that is about to be sent to Kuzzle, following the [Kuzzle API]({{ site_base_path }}api/1/essentials/query-syntax) format |
+| `reject` | <pre>function</pre> | A [Promise.reject](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/reject) function |
+| `resolve` | <pre>function</pre> | A [Promise.resolve](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/resolve) function |
+
+### queueFilter
+
+The `queueFilter` property must be set with a function of the following form:
+
+```js
+boolean queueFilter(request)
+```
+
+The `request` argument is an object representing the request that is about to be sent to Kuzzle, following the [Kuzzle API]({{ site_base_path }}api/1/essentials/query-syntax) format.
+
+### queueMaxSize
+
+This property defines the size of the offline buffer, which is a first-in first-out (FIFO) queue.
+
+This means that if the `queueMaxSize` limit is reached, older requests are discarded to make room for newer requests.
+
+If `queueMaxSize` is set to a number lower than, or equal to `0`, then an unlimited number of requests is kept in the offline buffer.  
+Note that doing so may lead to a crash due to memory saturation, if there are too many requests held in memory.
+
+### queueTTL
+
+If the `queueTTL` property is set to a number lower than, or equal to `0`, then requests never expire and are kept indefinitely.
+
+### volatile
+
+Multiple methods allow passing specific `volatile` data. 
+
+These `volatile` data will be merged with the global Kuzzle `volatile` object when sending the request, with the request specific `volatile` taking priority over the global ones.
+

src/sdk-reference/js/6/offline-tools/index.md

@@ -14,7 +14,7 @@ during its lifespan.
 
 These properties can be set in the `options` object when [instantiating a new SDK]({{ site_base_path }}sdk-reference/js/6/kuzzle/constructor/#arguments).  
 
-Some of them are also [writable properties]({{ site_base_path }}sdk-reference/js/6/kuzzle/introduction/#properties) available after SDK instantiation.
+Some of them are also [writable properties]({{ site_base_path }}sdk-reference/js/6/kuzzle/properties) available after SDK instantiation.
 
 ### autoQueue
 

src/sdk-reference/js/6/profile/introduction/index.md

@@ -10,19 +10,3 @@ order: 0
 This class represents a Kuzzle Profile.  
 
 Refer to the [Security guide]({{ site_base_path }}guide/1/essentials/security#defining-profiles-default) for more information about profiles.
-
-## Properties
-
-Available properties:
-
-| Property | Type | Description |
-|--- |--- |--- |
-| `_id` | <pre>string</pre> | Profile ID |
-| `policies` | <pre>object[]</pre> | Array of policies for this profile |
-
-Each policy object can contain the following properties:
-
-| Property | Type | Description |
-|--- |--- |--- |
-| `roleId` | <pre>string</pre> | Roles IDs for this user |
-| `restrictedTo` | <pre>object[]</pre> | Array of object containing indexes and collections which the profile is restricted to |

src/sdk-reference/js/6/profile/properties/index.md

@@ -0,0 +1,22 @@
+---
+layout: sdk.html.hbs
+title: Properties
+description: Profile Properties
+order: 100
+---
+
+# Properties
+
+| Property | Type | Description |
+|--- |--- |--- |
+| `_id` | <pre>string</pre> | Profile ID |
+| `policies` | <pre>object[]</pre> | Array of policies for this profile |
+
+### policies
+
+Each policy object can contain the following properties:
+
+| Property | Type | Description |
+|--- |--- |--- |
+| `roleId` | <pre>string</pre> | Roles IDs for this user |
+| `restrictedTo` | <pre>object[]</pre> | Array of object containing indexes and collections which the profile is restricted to |