Browse Source

Docs: Improved command API docs.

Piotrek Koszuliński 7 years ago
parent
commit
4078d0cf1a
1 changed files with 43 additions and 8 deletions
  1. 43 8
      packages/ckeditor5-core/src/command.js

+ 43 - 8
packages/ckeditor5-core/src/command.js

@@ -17,8 +17,8 @@ import mix from '@ckeditor/ckeditor5-utils/src/mix';
  * commands) to make changes in the model. Commands are available in every part of code that has access to
  * the {@link module:core/editor/editor~Editor editor} instance.
  *
- * Instances of registered commands can be retrieved from {@link module:core/editor/editor~Editor#commands}.
- * The easiest way to execute a command is through {@link module:core/editor/editor~Editor#execute}.
+ * Instances of registered commands can be retrieved from {@link module:core/editor/editor~Editor#commands `editor.commands`}.
+ * The easiest way to execute a command is through {@link module:core/editor/editor~Editor#execute `editor.execute()`}.
  *
  * By default commands are disabled when the editor is in {@link module:core/editor/editor~Editor#isReadOnly read-only} mode.
  *
@@ -40,12 +40,14 @@ export default class Command {
 		this.editor = editor;
 
 		/**
-		 * The value of a command. Concrete command class should define what it represents.
+		 * The value of the command. A concrete command class should define what it represents for it.
 		 *
-		 * For example, the `bold` command's value is whether the selection starts in a bolded text.
+		 * For example, the `bold` command's value indicates whether the selection starts in a bolded text.
 		 * And the value of the `link` command may be an object with links details.
 		 *
-		 * It's possible for a command to have no value (e.g. for stateless actions such as `imageUpload`).
+		 * It is possible for a command to have no value (e.g. for stateless actions such as `imageUpload`).
+		 *
+		 * A concrete command class should control this value by overriding the {@link #refresh `refresh()`} method.
 		 *
 		 * @observable
 		 * @readonly
@@ -55,7 +57,38 @@ export default class Command {
 
 		/**
 		 * Flag indicating whether a command is enabled or disabled.
-		 * A disabled command should do nothing when executed.
+		 * A disabled command will do nothing when executed.
+		 *
+		 * A concrete command class should control this value by overriding the {@link #refresh `refresh()`} method.
+		 *
+		 * It is possible to disable a command from "outside". For instance, in your integration you may want to disable
+		 * a certain set of commands for the time being. To do that, you can use the fact that `isEnabled` is observable
+		 * and it fires the `set:isEnabled` event every time anyone tries to modify its value:
+		 *
+		 *		function disableCommand( cmd ) {
+		 *			cmd.on( 'set:isEnabled', forceDisable, { priority: 'highest' } );
+		 *
+		 *			cmd.isEnabled = false;
+		 *
+		 *			// Make it possible to enable the command again.
+		 *			return () => {
+		 *				cmd.off( 'set:isEnabled', forceDisable );
+		 *				cmd.refresh();
+		 *			}
+		 *
+		 *			function forceDisable( evt ) {
+		 *				evt.return = false;
+		 *				evt.stop();
+		 *			}
+		 *		}
+		 *
+		 *		// Usage:
+		 *
+		 *		// Disabling the command.
+		 *		const enableBold = disableCommand( editor.commands.get( 'bold' ) );
+		 *
+		 *		// Enabling the command again.
+		 *		enableBold();
 		 *
 		 * @observable
 		 * @readonly
@@ -89,7 +122,7 @@ export default class Command {
 	}
 
 	/**
-	 * Refreshes the command. The command should update its {@link #isEnabled} and {@link #value} property
+	 * Refreshes the command. The command should update its {@link #isEnabled} and {@link #value} properties
 	 * in this method.
 	 *
 	 * This method is automatically called when
@@ -102,12 +135,14 @@ export default class Command {
 	/**
 	 * Executes the command.
 	 *
-	 * A command may accept parameters. They will be passed from {@link module:core/editor/editor~Editor#execute}
+	 * A command may accept parameters. They will be passed from {@link module:core/editor/editor~Editor#execute `editor.execute()`}
 	 * to the command.
 	 *
 	 * The `execute()` method will automatically abort when the command is disabled ({@link #isEnabled} is `false`).
 	 * This behavior is implemented by a high priority listener to the {@link #event:execute} event.
 	 *
+	 * In order to see how to disable a command from "outside" see the {@link #isEnbled} documentation.
+	 *
 	 * @fires execute
 	 */
 	execute() {}