Added documentation for key binding, contributions and registry

fixes #8636

Contributed on behalf of STMicroelectronics

Signed-off-by: Jonas Helming <jhelming@eclipsesource.com>

packages/core/src/browser/keybinding.ts

@@ -60,7 +60,7 @@ export interface ScopedKeybinding extends common.Keybinding {
 
 export const KeybindingContribution = Symbol('KeybindingContribution');
 /**
- * Representation of a keybinding contribution.
+ * Allows extensions to contribute {@link common.Keybinding}s
  */
 export interface KeybindingContribution {
  /**
@@ -168,36 +168,36 @@ export class KeybindingRegistry {
  *
  * Keybindings registered later have higher priority during evaluation.
  *
- * @param binding
+ * @param binding the keybinding to be registered
  */
  registerKeybinding(binding: common.Keybinding): Disposable {
  return this.doRegisterKeybinding(binding);
  }
 
  /**
- * Register default keybindings to the registry
+ * Register multiple default keybindings to the registry
  *
- * @param bindings
+ * @param bindings An array of keybinding to be registered
  */
  registerKeybindings(...bindings: common.Keybinding[]): Disposable {
  return this.doRegisterKeybindings(bindings, KeybindingScope.DEFAULT);
  }
 
  /**
- * Unregister keybindings from the registry using the key of the given keybinding
+ * Unregister all keybindings from the registry that are bound to the key of the given keybinding
  *
- * @param binding a Keybinding specifying the key to be unregistered
+ * @param binding a keybinding specifying the key to be unregistered
  */
  unregisterKeybinding(binding: common.Keybinding): void;
  /**
- * Unregister keybindings with the given key from the registry
+ * Unregister all keybindings with the given key from the registry
  *
  * @param key a key to be unregistered
  */
  unregisterKeybinding(key: string): void;
  /**
  * Unregister all existing keybindings for the given command
- * @param command the command to unregister keybindings for
+ * @param command the command to unregister all keybindings for
  */
  unregisterKeybinding(command: Command): void;
 
@@ -266,6 +266,12 @@ export class KeybindingRegistry {
  }
  }
 
+ /**
+ * Checks whether a colliding {@link common.Keybinding} exists in a specific scope.
+ * @param binding the keybinding to check
+ * @param scope the keybinding scope to check
+ * @returns true if there is a colliding keybinding
+ */
  containsKeybindingInScope(binding: common.Keybinding, scope = KeybindingScope.USER): boolean {
  const bindingKeySequence = this.resolveKeybinding(binding);
  const collisions = this.getKeySequenceCollisions(this.keymaps[scope], bindingKeySequence)
@@ -283,22 +289,31 @@ export class KeybindingRegistry {
  }
 
  /**
- * Return a user visible representation of a keybinding.
+ * Get a user visible representation of a {@link common.Keybinding}.
+ * @returns an array of strings representing all elements of the {@link KeySequence} defined by the {@link common.Keybinding}
+ * @param keybinding the keybinding
+ * @param separator the separator to be used to stringify {@link KeyCode}s that are part of the {@link KeySequence}
  */
  acceleratorFor(keybinding: common.Keybinding, separator: string = ' '): string[] {
  const bindingKeySequence = this.resolveKeybinding(keybinding);
  return this.acceleratorForSequence(bindingKeySequence, separator);
  }
 
  /**
- * Return a user visible representation of a key sequence.
+ * Get a user visible representation of a {@link KeySequence}.
+ * @returns an array of strings representing all elements of the {@link KeySequence}
+ * @param keySequence the keysequence
+ * @param separator the separator to be used to stringify {@link KeyCode}s that are part of the {@link KeySequence}
  */
  acceleratorForSequence(keySequence: KeySequence, separator: string = ' '): string[] {
  return keySequence.map(keyCode => this.acceleratorForKeyCode(keyCode, separator));
  }
 
  /**
- * Return a user visible representation of a key code (a key with modifiers).
+ * Get a user visible representation of a key code (a key with modifiers).
+ * @returns a string representing the {@link KeyCode}
+ * @param keyCode the {@link KeyCode}
+ * @param separator the separator used to separate keys (key and modifiers) in the returning string
  */
  acceleratorForKeyCode(keyCode: KeyCode, separator: string = ' '): string {
  const keyCodeResult = [];
@@ -383,9 +398,10 @@ export class KeybindingRegistry {
  }
 
  /**
- * Get the keybindings associated to commandId.
+ * Get all keybindings associated to a commandId.
  *
  * @param commandId The ID of the command for which we are looking for keybindings.
+ * @returns an array of {@link ScopedKeybinding}
  */
  getKeybindingsForCommand(commandId: string): ScopedKeybinding[] {
  const result: ScopedKeybinding[] = [];
@@ -577,6 +593,11 @@ export class KeybindingRegistry {
  return commandId === KeybindingRegistry.PASSTHROUGH_PSEUDO_COMMAND;
  }
 
+ /**
+ * Sets a new keymap replacing all existing {@link common.Keybinding}s in the given scope.
+ * @param scope the keybinding scope
+ * @param bindings an array containing the new {@link common.Keybinding}s
+ */
  setKeymap(scope: KeybindingScope, bindings: common.Keybinding[]): void {
  this.resetKeybindingsForScope(scope);
  this.toResetKeymap.set(scope, this.doRegisterKeybindings(bindings, scope));
@@ -605,6 +626,11 @@ export class KeybindingRegistry {
  }
  }
 
+ /**
+ * Get all {@link common.Keybinding}s for a {@link KeybindingScope}.
+ * @returns an array of {@link common.ScopedKeybinding}
+ * @param scope the keybinding scope to retrieve the {@link common.Keybinding}s for.
+ */
  getKeybindingsByScope(scope: KeybindingScope): ScopedKeybinding[] {
  return this.keymaps[scope];
  }

packages/core/src/common/keybinding.ts

@@ -13,11 +13,19 @@
  *
  * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
  ********************************************************************************/
-
+/**
+ * A Keybinding binds a specific key sequence ({@link Keybinding#keybinding}) to trigger a command ({@link Keybinding#command}). A Keybinding optionally may
+ * define a "when clause" ({@link Keybinding#when}) to specify in which context it becomes active.
+ * @see KeyBindingRegistry
+ */
 export interface Keybinding {
- /** Command identifier, this needs to be a unique string. */
+ /**
+ * Unique command identifier of the command to be triggered by this keybinding.
+ */
  command: string;
- /** Keybinding string as defined in packages/keymaps/README.md. */
+ /**
+ * The key sequence for the keybinding as defined in packages/keymaps/README.md.
+ */
  keybinding: string;
  /**
  * The optional keybinding context where this binding belongs to.
@@ -28,12 +36,14 @@ export interface Keybinding {
  */
  context?: string;
  /**
- * https://code.visualstudio.com/docs/getstarted/keybindings#_when-clause-contexts
+ * An optional clause defining the condition when the keybinding is active, e.g. based on the current focus.
+ * See {@link https://code.visualstudio.com/docs/getstarted/keybindings#_when-clause-contexts} for more details.
  */
  when?: string;
 
  /**
- * Specified when the command has arguments that are passed to the command handler.
+ * Optional arguments that will be passed to the command when it gets triggered via this keybinding.
+ * Needs to be specified when the triggered command expects arguments to be passed to the command handler.
  */
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  args?: any;