doc: document overload of SharedState#set

misc/assets/custom.css

@@ -95,8 +95,8 @@ h1 > code {
 }
 
 h4.name {
-  color: #282922;
-  background: #dedede;
+  color: #ffffff;
+  background: #282922;
   border-top: 1px solid #efefef;
   box-shadow: 0 0.05em 0.1em #e1e1e1;
 }
@@ -106,26 +106,26 @@ h4.name {
 }
 
 .signature {
-  color: #3e4035;
+  color: #eeefea;
 }
 
 .signature-attributes {
   font-size: 60%;
-  color: #616354;
+  color: #a2a29e;
   font-style: italic;
   font-weight: lighter;
 }
 
 .type-signature {
-  color: #3e4035;
+  color: #eeefea;
 }
 
 .type-signature:last-child {
-  color: #616354;
+  color: #a2a29e;
 }
 
 h4.name a {
-  color: #3e4035;
+  color: #afafab;
 }
 
 h4.name a:hover {

src/common/SharedState.js

@@ -379,11 +379,31 @@ ${JSON.stringify(initValues, null, 2)}`);
   }
 
   /**
-   * Update values of the state.
+   * Update the values of the state.
    *
    * The returned `Promise` resolves on an object that contains the applied updates,
-   * and resolves after all the `onUpdate` callbacks have resolved themselves, i.e.:
+   * and resolves after all the `onUpdate` callbacks have resolved themselves
+   *
+   * @overload
+   * @param {object} updates - Key / value pairs of updates to apply to the state.
+   * @returns {Promise<Object>} - Promise to the (coerced) updates.
+   */
+  /**
+   * Update the values of the state.
+   *
+   * The returned `Promise` resolves on an object that contains the applied updates,
+   * and resolves after all the `onUpdate` callbacks have resolved themselves
    *
+   * @overload
+   * @param {SharedStateParameterName} name - Name of the parameter.
+   * @param {*} value - Value of the parameter.
+   * @returns {Promise<Object>} - Promise to the (coerced) updates.
+   */
+  /**
+   * Update the values of the state.
+   *
+   * The returned `Promise` resolves on an object that contains the applied updates,
+   * and resolves after all the `onUpdate` callbacks have resolved themselves, i.e.:
    * ```js
    * server.stateManager.defineClass('test', {
    *   myBool: { type: 'boolean', default: false },
@@ -406,8 +426,12 @@ ${JSON.stringify(initValues, null, 2)}`);
    * assert.deepEqual(updates, { myBool: true });
    * ```
    *
+   * Alternative signatures:
+   * - `await state.set(updates)`
+   * - `await state.set(name, value)`
+   *
    * @param {object} updates - Key / value pairs of updates to apply to the state.
-   * @returns {Promise<Object>} A promise to the (coerced) updates.
+   * @returns {Promise<Object>} - Promise to the (coerced) updates.
    *
    * @example
    * const state = await client.stateManager.attach('globals');

src/common/SharedStateCollection.js

@@ -115,7 +115,7 @@ class SharedStateCollection {
   }
 
   /**
-   * @deprecated Use ${@link SharedStateCollection#className} instead.
+   * @deprecated Use {@link SharedStateCollection#className} instead.
    */
   get schemaName() {
     logger.deprecated('SharedStateCollection#schemaName', 'SharedStateCollection#className', '4.0.0-alpha.29');
@@ -222,7 +222,40 @@ class SharedStateCollection {
 
   /**
    * Update all states of the collection with given values.
-   * @param {object} updates - key / value pairs of updates to apply to the state.
+   *
+   * The returned `Promise` resolves on a list of objects that contains the applied updates,
+   * and resolves after all the `onUpdate` callbacks have resolved themselves
+   *
+   * @overload
+   * @param {object} updates - key / value pairs of updates to apply to the collection.
+   * @returns {Promise<Array<Object>>} - Promise to the list of (coerced) updates.
+   */
+  /**
+   * Update all states of the collection with given values.
+   *
+   * The returned `Promise` resolves on a list of objects that contains the applied updates,
+   * and resolves after all the `onUpdate` callbacks have resolved themselves
+   *
+   * @overload
+   * @param {SharedStateParameterName} name - Name of the parameter.
+   * @param {*} value - Value of the parameter.
+   * @returns {Promise<Array<Object>>} - Promise to the list of (coerced) updates.
+   */
+  /**
+   * Update all states of the collection with given values.
+   *
+   * The returned `Promise` resolves on a list of objects that contains the applied updates,
+   * and resolves after all the `onUpdate` callbacks have resolved themselves
+   *
+   * Alternative signatures:
+   * - `await collection.set(updates)`
+   * - `await collection.set(name, value)`
+   *
+   * @param {object} updates - key / value pairs of updates to apply to the collection.
+   * @returns {Promise<Array<Object>>} - Promise to the list of (coerced) updates.
+   * @example
+   * const collection = await client.stateManager.getCollection('globals');
+   * const updates = await collection.set({ myParam: Math.random() });
    */
   async set(...args) {
     // we can delegate to the state.set(update) method for throwing in case of

types/client/ClientStateManager.d.ts

@@ -6,14 +6,15 @@ export type ClientStateManager = () => any;
 /**
  * @callback ClientStateManager~ObserveCallback
  * @async
- * @param {String} schemaName - name of the schema
- * @param {Number} stateId - id of the state
- * @param {Number} nodeId - id of the node that created the state
+ * @param {String} className - Name of the shared state class.
+ * @param {Number} stateId - Id of the state.
+ * @param {Number} nodeId - Id of the node that created the state.
  */
 /**
  * The `ClientStateManager` allows to create new {@link SharedState}s, or attach
- * to {@link SharedState}s created by other nodes (clients or server). It
- * can also track all the {@link SharedState}s created by other nodes.
+ * to {@link SharedState}s created by other nodes (clients or server) on the network.
+ *
+ * It can also observe all the {@link SharedState}s created on the network.
  *
  * An instance of `ClientStateManager` is automatically created by the `soundworks.Client`
  * at initialization (cf. {@link client.Client#stateManager}).
@@ -27,8 +28,8 @@ export type ClientStateManager = () => any;
  * import { Server } from '@soundworks/server/index.js';
  *
  * const server = new Server(config);
- * // declare and register the schema of a shared state.
- * server.stateManager.registerSchema('some-global-state', {
+ * // define a class of shared state.
+ * server.stateManager.defineClass('some-global-state', {
  *   myRandom: {
  *     type: 'float',
  *     default: 0,

types/common/BasePlugin.d.ts

@@ -74,7 +74,7 @@ declare class BasePlugin {
      *   constructor(server, id) {
      *     super(server, id);
      *
-     *     this.server.stateManager.registerSchema(`my-plugin:${this.id}`, {
+     *     this.server.stateManager.defineClass(`my-plugin:${this.id}`, {
      *       someParam: {
      *         type: 'boolean',
      *         default: false,
@@ -106,7 +106,7 @@ declare class BasePlugin {
      *   constructor(server, id) {
      *     super(server, id);
      *
-     *     this.server.stateManager.registerSchema(`my-plugin:${this.id}`, {
+     *     this.server.stateManager.defineClass(`my-plugin:${this.id}`, {
      *       someParam: {
      *         type: 'boolean',
      *         default: false,