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]>

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 |

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

@@ -10,12 +10,3 @@ order: 0
 This class represents a Kuzzle Role.  
 
 Refer to the [Security guide]({{ site_base_path }}guide/1/essentials/security#defining-roles-default) for more information about roles.
-
-## Properties
-
-Available properties:
-
-| Property | Type | Description |
-|--- |--- |--- |
-| `_id` | <pre>string</pre> | Role ID |
-| `controllers` | <pre>object</pre> | Object defining controllers action available for this role |

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

@@ -0,0 +1,15 @@
+---
+layout: sdk.html.hbs
+title: Properties
+description: Role class properties
+order: 100
+---
+
+# Properties
+
+Available properties:
+
+| Property | Type | Description |
+|--- |--- |--- |
+| `_id` | <pre>string</pre> | Role unique identifier |
+| `controllers` | <pre>object</pre> | Object defining controller actions allowed by this role |

src/sdk-reference/js/6/search-result/introduction/index.md

@@ -11,23 +11,3 @@ The class is used to retrieve the subsequent paginated results of a search query
 The following methods returns a `SearchResult`:
  - [document:search]({{ site_base_path }}sdk-reference/js/6/document/search)
  - [collection:searchSpecifications]({{ site_base_path }}sdk-reference/js/6/collection/search-specifications)
-
-## Properties
-
-Available properties.
-
-| Property | Type | Description |
-|--- |--- |--- |
-| `aggregations` | <pre>object</pre> | Search aggregations if any |
-| `hits` | <pre>object[]</pre> | Array containing the retrieved items for the current page |
-| `total` | <pre>number</pre> |  Total number of items matching the given query in Kuzzle database |
-| `fetched` | <pre>number</pre> | Number of retrieved items so far |
-| `scroll_id` | <pre>string</pre> | Scroll identifier if the search was given a `scroll` parameter |
-
-Each object of the `hits` array contain the following properties:
-
-| Property | Type | Description |
-|--- |--- |--- |
-| `_id` | <pre>string</pre> | Document ID |
-| `_score` | <pre>number</pre> | [Relevance score](https://www.elastic.co/guide/en/elasticsearch/guide/current/relevance-intro.html) |
-| `_source` | <pre>object</pre> | Document content |

src/sdk-reference/js/6/search-result/properties/index.md

@@ -0,0 +1,26 @@
+---
+layout: sdk.html.hbs
+title: Properties
+description: SearchResult class properties
+order: 1000
+---
+
+# Properties
+
+| Property | Type | Description |
+|--- |--- |--- |
+| `aggregations` | <pre>object</pre> | Search aggregations if any |
+| `hits` | <pre>object[]</pre> | Array containing the retrieved items for the current page |
+| `total` | <pre>number</pre> |  Total number of items matching the given query in Kuzzle database |
+| `fetched` | <pre>number</pre> | Number of retrieved items so far |
+| `scroll_id` | <pre>string</pre> | Scroll identifier if the search was given a `scroll` parameter |
+
+### hits
+
+Each object of the `hits` array contain the following properties:
+
+| Property | Type | Description |
+|--- |--- |--- |
+| `_id` | <pre>string</pre> | Document ID |
+| `_score` | <pre>number</pre> | [Relevance score](https://www.elastic.co/guide/en/elasticsearch/guide/current/relevance-intro.html) |
+| `_source` | <pre>object</pre> | Document content |

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

@@ -15,16 +15,3 @@ This protocol allows you to use all the features of Kuzzle, including [real-time
   The SocketIO protocol is used for websocket compatibility with older browsers. It is preferable to use the <a href="{{ site_base_path }}sdk-reference/js/6/websocket">WebSocket</a> protocol when possible.
   </p>
 </div>
-
-## Properties
-
-Available properties.
-
-| Property name        | Type     | Description          | Writable? |
-| -------------------- | -------- | --------------------------------------- | :-------: |
-| `autoReconnect`      | <pre>boolean</pre> | Automatically reconnect after a connection loss    |    No     |
-| `reconnectionDelay`  | <pre>number</pre>  | Number of milliseconds between reconnection attempts         |    No     |
-
-**Notes:**
-
-- updates to `autoReconnect` and `reconnectionDelay` properties will only take effect on next `connect` call

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

@@ -0,0 +1,17 @@
+---
+layout: sdk.html.hbs
+title: Properties
+description: SocketIO class properties
+order: 100
+---
+
+# Properties
+
+| Property name        | Type     | Description          |
+| -------------------- | -------- | ---------------------|
+| `autoReconnect` | <pre>boolean</pre> | Automatically reconnect after a connection loss |
+| `reconnectionDelay` | <pre>number</pre>  | Number of milliseconds between reconnection attempts |
+
+<div class="alert alert-info">
+Updates to <code>autoReconnect</code> and <code>reconnectionDelay</code> properties will only take effect on the next `connect` call.
+</div>