瀏覽代碼

Another set of docs improvements with decorators.

Mateusz Samsel 6 年之前
父節點
當前提交
317bf6fd9e

+ 12 - 4
packages/ckeditor5-link/src/linkcommand.js

@@ -69,19 +69,27 @@ export default class LinkCommand extends Command {
 	 *
 	 * When the selection is collapsed and inside the text with the `linkHref` attribute, the attribute value will be updated.
 	 *
+	 * # Decorators
+	 * Command has an optional second parameter, which can apply or remove {@link module:link/utils~ManualDecorator} together with href.
+	 * Decorators are representing in a corresponding way as href, which are attributes for {@link module:engine/model/text~Text Text node}.
+	 * Names of those attributes are stored as `id`s in {@link module:link/utils~ManualDecorator} and preserve convention of name:
+	 * `linkManualDecoratorN`, where `N` is replaced with a number (for example: `'linkManualDecorator0'`).
+	 *
+	 * More about decorators might be found in {@link module:link/link~LinkConfig#decorators}
+	 *
 	 * @fires execute
 	 * @param {String} href Link destination.
-	 * @param {Object} [manualDecorators={}] Keeps information about turned on and off manual decorators applied with command.
+	 * @param {Object} [manualDecoratorIds={}] Keeps information about turned on and off manual decorators applied with command.
 	 */
-	execute( href, manualDecorators = {} ) {
+	execute( href, manualDecoratorIds = {} ) {
 		const model = this.editor.model;
 		const selection = model.document.selection;
 		// Stores information about manual decorators to turn them on/off when command is applied.
 		const truthyManualDecorators = [];
 		const falsyManualDecorators = [];
 
-		for ( const name in manualDecorators ) {
-			if ( manualDecorators[ name ] ) {
+		for ( const name in manualDecoratorIds ) {
+			if ( manualDecoratorIds[ name ] ) {
 				truthyManualDecorators.push( name );
 			} else {
 				falsyManualDecorators.push( name );

+ 10 - 12
packages/ckeditor5-link/src/linkediting.js

@@ -90,13 +90,11 @@ export default class LinkEditing extends Plugin {
 	}
 
 	/**
-	 * Method process {@link module:link/link~LinkDecoratorAutomaticOption} by creating instance of
-	 * {@link module:link/utils~AutomaticDecorators}. If there are available automatic decorators, then
-	 * there is registered {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher} to handle
-	 * those configurations.
+	 * Method process array of {@link module:link/link~LinkDecoratorAutomaticOption} and register
+	 * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher downcast dispatcher} for them.
+	 * Downcast dispatcher is obtained with {@link module:link/utils~AutomaticDecorators#getDispatcher}.
 	 *
-	 * Please notice, that automatic decorator will be also added, when {@link module:link/link~LinkConfig#targetDecorator}
-	 * will be set to `true`.
+	 * Method also kept configuration of decorator activated with {@link module:link/link~LinkConfig#targetDecorator}.
 	 *
 	 * @private
 	 * @param {Array.<module:link/link~LinkDecoratorAutomaticOption>} automaticDecoratorDefinitions
@@ -125,12 +123,12 @@ export default class LinkEditing extends Plugin {
 	}
 
 	/**
-	 * Method process {@link module:link/link~LinkDecoratorManualOption} by transformation those configuration options into
-	 * {@link module:link/utils~ManualDecorator}. Manual decorators are added to
-	 * {@link module:link/linkcommand~LinkCommand#manualDecorators} collections, which might be considered as a model
-	 * for manual decorators state. It also provides proper
-	 * {@link module:engine/conversion/downcasthelpers~DowncastHelpers#attributeToElement attributeToElement} converter for each
-	 * manual decorator and extends {@link module:engine/model/schema~Schema model's schema} with adequate model attributes.
+	 * Method process array of {@link module:link/link~LinkDecoratorManualOption} by transformation those configuration options into
+	 * {@link module:link/utils~ManualDecorator} objects. Then those objects are added to
+	 * {@link module:link/linkcommand~LinkCommand#manualDecorators} collection, which is considered as a model for manual decorators state.
+	 * It also provides a proper {@link module:engine/conversion/downcasthelpers~DowncastHelpers#attributeToElement attributeToElement}
+	 * converter for each manual decorator and extends the {@link module:engine/model/schema~Schema model's schema}
+	 * with adequate model attributes.
 	 *
 	 * @private
 	 * @param {Array.<module:link/link~LinkDecoratorManualOption>} manualDecoratorDefinitions

+ 6 - 3
packages/ckeditor5-link/src/ui/linkformview.js

@@ -85,7 +85,9 @@ export default class LinkFormView extends View {
 		this.cancelButtonView = this._createButton( t( 'Cancel' ), cancelIcon, 'ck-button-cancel', 'cancel' );
 
 		/**
-		 * Keeps reference to {@link module:link/linkcommand~LinkCommand#manualDecorators}.
+		 * Keeps reference to {@link module:link/linkcommand~LinkCommand#manualDecorators} in link command.
+		 * Collection is used to build proper UI element and synchronize its state between model located in
+		 * {@link module:link/linkcommand~LinkCommand#manualDecorators link command} and the {@link #manualDecoratorsUIView UI}.
 		 *
 		 * @readonly
 		 * @type {model:utils/collection~Collection}
@@ -93,8 +95,9 @@ export default class LinkFormView extends View {
 		this.manualDecorators = manualDecorators;
 
 		/**
-		 * Keeps reference to {@link module:ui/button/switchbuttonview~SwitchButtonView} made based on {@link #manualDecorators}.
-		 * It use {@link #_createManualDecoratorsUIView} to generate proper collection.
+		 * Preserves collection of {@link module:ui/button/switchbuttonview~SwitchButtonView},
+		 * which are made based on {@link #manualDecorators}. It use {@link #_createManualDecoratorsUIView} method
+		 * to generate proper collection.
 		 *
 		 * @readonly
 		 * @type {module:ui/viewcollection~ViewCollection}

+ 6 - 5
packages/ckeditor5-link/src/utils/automaticdecorators.js

@@ -8,13 +8,14 @@
  */
 
 /**
- * Helper class which stores information about automatic decorators for link plugin
- * and provides dispatcher which applies all of them to the view.
+ * Helper class which tight together all {@link module:link/link~LinkDecoratorAutomaticOption} and provides
+ * a {@link module:engine/conversion/downcasthelpers~DowncastHelpers#attributeToElement downcast dispatcher} for them.
  */
 export default class AutomaticDecorators {
 	constructor() {
 		/**
-		 * Stores definition of automatic decorators. Based on those values proper conversion has happens.
+		 * Stores definition of {@link module:link/link~LinkDecoratorAutomaticOption automatic decorators}.
+		 * Those data are used as source for a downcast dispatcher to make proper conversion to output data.
 		 *
 		 * @private
 		 * @type {Set}
@@ -34,7 +35,7 @@ export default class AutomaticDecorators {
 	}
 
 	/**
-	 * Add item or array of items with automatic rules for applying decorators to link plugin.
+	 * Add automatic decorator objects or array with them to be used during downcasting.
 	 *
 	 * @param {module:link/link~LinkDecoratorAutomaticOption|Array.<module:link/link~LinkDecoratorAutomaticOption>} item
 	 * configuration object of automatic rules for decorating links. It might be also array of such objects.
@@ -48,7 +49,7 @@ export default class AutomaticDecorators {
 	}
 
 	/**
-	 * Gets the conversion helper used in {@link module:engine/conversion/downcasthelpers~DowncastHelpers#add} method.
+	 * Provides the conversion helper used in an {@link module:engine/conversion/downcasthelpers~DowncastHelpers#add} method.
 	 *
 	 * @returns {Function} dispatcher function used as conversion helper
 	 * in {@link module:engine/conversion/downcasthelpers~DowncastHelpers#add}

+ 10 - 8
packages/ckeditor5-link/src/utils/manualdecorator.js

@@ -11,8 +11,9 @@ import ObservableMixin from '@ckeditor/ckeditor5-utils/src/observablemixin';
 import mix from '@ckeditor/ckeditor5-utils/src/mix';
 
 /**
- * Class which stores manual decorators with observable {@link module:link/utils~ManualDecorator#value}
- * to handle integration with ui state.
+ * Helper class which stores manual decorators with observable {@link module:link/utils~ManualDecorator#value}
+ * to support integration with the UI state. An instance of this class is a model with state of single manual decorators.
+ * These decorators are kept as collections in {@link module:link/linkcommand~LinkCommand#manualDecorators}.
  *
  * @mixes module:utils/observablemixin~ObservableMixin
  */
@@ -21,14 +22,15 @@ export default class ManualDecorator {
 	 * Creates new instance of {@link module:link/utils~ManualDecorator}.
 	 *
 	 * @param {Object} config
-	 * @param {String} config.id Manual decorator id, which is a name of attribute in model, for example 'linkManualDecorator0'.
-	 * @param {String} config.label The label used in user interface to switch manual decorator.
-	 * @param {Object} config.attributes Set of attributes added to downcasted data, when decorator is activated for specific link.
-	 * Attributes should be added in a form of attributes defined in {@link module:engine/view/elementdefinition~ElementDefinition}.
+	 * @param {String} config.id name of attribute used in model, which represents given manual decorator.
+	 * For example 'linkManualDecorator0'.
+	 * @param {String} config.label The label used in user interface to toggle manual decorator.
+	 * @param {Object} config.attributes Set of attributes added to output data, when decorator is active for specific link.
+	 * Attributes should keep format of attributes defined in {@link module:engine/view/elementdefinition~ElementDefinition}.
 	 */
 	constructor( { id, label, attributes } ) {
 		/**
-		 * Manual decorator id, which is a name of attribute in model, for example 'linkManualDecorator0'.
+		 * Id of manual decorator, which is a name of attribute in model, for example 'linkManualDecorator0'.
 		 *
 		 * @type {String}
 		 */
@@ -43,7 +45,7 @@ export default class ManualDecorator {
 		this.set( 'value' );
 
 		/**
-		 * The label used in user interface to switch manual decorator.
+		 * The label used in user interface to toggle manual decorator.
 		 *
 		 * @type {String}
 		 */