improve documentation

docs/development/core/server/kibana-plugin-server.capabilitiessetup.md

@@ -6,6 +6,12 @@
 
 APIs to manage the [Capabilities](./kibana-plugin-server.capabilities.md) that will be used by the application.
 
+Plugins relying on capabilities to toggle some of their features should register them during the setup phase using the `registerProvider` method.
+
+Plugins having the responsibility to restrict capabilities depending on a given context should register their capabilities switcher using the `registerSwitcher` method.
+
+Refers to the methods documentation for complete description and examples.
+
 <b>Signature:</b>
 
 ```typescript
@@ -16,6 +22,6 @@ export interface CapabilitiesSetup
 
 |  Method | Description |
 |  --- | --- |
-|  [registerProvider(provider)](./kibana-plugin-server.capabilitiessetup.registerprovider.md) | Register a [CapabilitiesProvider](./kibana-plugin-server.capabilitiesprovider.md) to be used when resolving capabilities. |
-|  [registerSwitcher(switcher)](./kibana-plugin-server.capabilitiessetup.registerswitcher.md) | Register a [CapabilitiesSwitcher](./kibana-plugin-server.capabilitiesswitcher.md) to be used when resolving capabilities. |
+|  [registerProvider(provider)](./kibana-plugin-server.capabilitiessetup.registerprovider.md) | Register a [CapabilitiesProvider](./kibana-plugin-server.capabilitiesprovider.md) to be used to provide [Capabilities](./kibana-plugin-server.capabilities.md) when resolving them. |
+|  [registerSwitcher(switcher)](./kibana-plugin-server.capabilitiessetup.registerswitcher.md) | Register a [CapabilitiesSwitcher](./kibana-plugin-server.capabilitiesswitcher.md) to be used to change the default state of the [Capabilities](./kibana-plugin-server.capabilities.md) entries when resolving them.<!-- -->A capabilities switcher can only change the state of existing capabilities. Capabilities added or removed when invoking the switcher will be ignored. |
 

docs/development/core/server/kibana-plugin-server.capabilitiessetup.registerprovider.md

@@ -4,7 +4,7 @@
 
 ## CapabilitiesSetup.registerProvider() method
 
-Register a [CapabilitiesProvider](./kibana-plugin-server.capabilitiesprovider.md) to be used when resolving capabilities.
+Register a [CapabilitiesProvider](./kibana-plugin-server.capabilitiesprovider.md) to be used to provide [Capabilities](./kibana-plugin-server.capabilities.md) when resolving them.
 
 <b>Signature:</b>
 
@@ -24,6 +24,7 @@ registerProvider(provider: CapabilitiesProvider): void;
 
 ## Example
 
+How to register a plugin's capabilities during setup
 
 ```ts
 // my-plugin/server/plugin.ts
@@ -34,10 +35,11 @@ public setup(core: CoreSetup, deps: {}) {
          myPlugin: true,
        },
        myPlugin: {
-         feature: true,
+         someFeature: true,
+         featureDisabledByDefault: false,
        },
      }
-   })
+   });
 }
 
 ```

docs/development/core/server/kibana-plugin-server.capabilitiessetup.registerswitcher.md

@@ -4,7 +4,9 @@
 
 ## CapabilitiesSetup.registerSwitcher() method
 
-Register a [CapabilitiesSwitcher](./kibana-plugin-server.capabilitiesswitcher.md) to be used when resolving capabilities.
+Register a [CapabilitiesSwitcher](./kibana-plugin-server.capabilitiesswitcher.md) to be used to change the default state of the [Capabilities](./kibana-plugin-server.capabilities.md) entries when resolving them.
+
+A capabilities switcher can only change the state of existing capabilities. Capabilities added or removed when invoking the switcher will be ignored.
 
 <b>Signature:</b>
 
@@ -22,22 +24,23 @@ registerSwitcher(switcher: CapabilitiesSwitcher): void;
 
 `void`
 
-## Remarks
-
-A capabilities switcher can only change the state of existing capabilities. capabilities added or removed when invoking the switcher will be ignored.
-
 ## Example
 
+How to restrict some capabilities
 
 ```ts
 // my-plugin/server/plugin.ts
 public setup(core: CoreSetup, deps: {}) {
    core.capabilities.registerSwitcher((request, capabilities) => {
-     if(myPluginApi.shouldRestrictBecauseOf(request)) {
-       return myPluginApi.disableSomeCapabilities(capabilities);
+     if(myPluginApi.shouldRestrictSomePluginBecauseOf(request)) {
+       return {
+         somePlugin: {
+           featureEnabledByDefault: false // `featureEnabledByDefault` will be disabled. All other capabilities will remain unchanged.
+         }
+       }
      }
-     return capabilities;
-   })
+     return {}; // All capabilities will remain unchanged.
+   });
 }
 
 ```

docs/development/core/server/kibana-plugin-server.md

@@ -44,7 +44,7 @@ The plugin integrates with the core system via lifecycle events: `setup`<!-- -->
 |  [AuthToolkit](./kibana-plugin-server.authtoolkit.md) | A tool set defining an outcome of Auth interceptor for incoming request. |
 |  [CallAPIOptions](./kibana-plugin-server.callapioptions.md) | The set of options that defines how API call should be made and result be processed. |
 |  [Capabilities](./kibana-plugin-server.capabilities.md) | The read-only set of capabilities available for the current UI session. Capabilities are simple key-value pairs of (string, boolean), where the string denotes the capability ID, and the boolean is a flag indicating if the capability is enabled or disabled. |
-|  [CapabilitiesSetup](./kibana-plugin-server.capabilitiessetup.md) | APIs to manage the [Capabilities](./kibana-plugin-server.capabilities.md) that will be used by the application. |
+|  [CapabilitiesSetup](./kibana-plugin-server.capabilitiessetup.md) | APIs to manage the [Capabilities](./kibana-plugin-server.capabilities.md) that will be used by the application.<!-- -->Plugins relying on capabilities to toggle some of their features should register them during the setup phase using the <code>registerProvider</code> method.<!-- -->Plugins having the responsibility to restrict capabilities depending on a given context should register their capabilities switcher using the <code>registerSwitcher</code> method.<!-- -->Refers to the methods documentation for complete description and examples. |
 |  [CapabilitiesStart](./kibana-plugin-server.capabilitiesstart.md) | APIs to access the application [Capabilities](./kibana-plugin-server.capabilities.md)<!-- -->. |
 |  [ContextSetup](./kibana-plugin-server.contextsetup.md) | An object that handles registration of context providers and configuring handlers with context. |
 |  [CoreSetup](./kibana-plugin-server.coresetup.md) | Context passed to the plugins <code>setup</code> method. |

src/core/server/capabilities/capabilities_service.ts

@@ -28,6 +28,14 @@ import { registerRoutes } from './routes';
 /**
  * APIs to manage the {@link Capabilities} that will be used by the application.
  *
+ * Plugins relying on capabilities to toggle some of their features should register them during the setup phase
+ * using the `registerProvider` method.
+ *
+ * Plugins having the responsibility to restrict capabilities depending on a given context should register
+ * their capabilities switcher using the `registerSwitcher` method.
+ *
+ * Refers to the methods documentation for complete description and examples.
+ *
  * @public
  */
 export interface CapabilitiesSetup {
@@ -36,6 +44,7 @@ export interface CapabilitiesSetup {
    * when resolving them.
    *
    * @example
+   * How to register a plugin's capabilities during setup
    * ```ts
    * // my-plugin/server/plugin.ts
    * public setup(core: CoreSetup, deps: {}) {
@@ -45,10 +54,11 @@ export interface CapabilitiesSetup {
    *          myPlugin: true,
    *        },
    *        myPlugin: {
-   *          feature: true,
+   *          someFeature: true,
+   *          featureDisabledByDefault: false,
    *        },
    *      }
-   *    })
+   *    });
    * }
    * ```
    */
@@ -58,22 +68,26 @@ export interface CapabilitiesSetup {
    * Register a {@link CapabilitiesSwitcher} to be used to change the default state
    * of the {@link Capabilities} entries when resolving them.
    *
+   * A capabilities switcher can only change the state of existing capabilities.
+   * Capabilities added or removed when invoking the switcher will be ignored.
+   *
    * @example
+   * How to restrict some capabilities
    * ```ts
    * // my-plugin/server/plugin.ts
    * public setup(core: CoreSetup, deps: {}) {
    *    core.capabilities.registerSwitcher((request, capabilities) => {
-   *      if(myPluginApi.shouldRestrictBecauseOf(request)) {
-   *        return myPluginApi.disableSomeCapabilities(capabilities);
+   *      if(myPluginApi.shouldRestrictSomePluginBecauseOf(request)) {
+   *        return {
+   *          somePlugin: {
+   *            featureEnabledByDefault: false // `featureEnabledByDefault` will be disabled. All other capabilities will remain unchanged.
+   *          }
+   *        }
    *      }
-   *      return capabilities;
-   *    })
+   *      return {}; // All capabilities will remain unchanged.
+   *    });
    * }
    * ```
-   *
-   * @remarks
-   * A capabilities switcher can only change the state of existing capabilities.
-   * capabilities added or removed when invoking the switcher will be ignored.
    */
   registerSwitcher(switcher: CapabilitiesSwitcher): void;
 }