浏览代码

Docs: Refactoring of the decorators documentation in link feature classes.

Aleksander Nowodzinski 6 年之前
父节点
当前提交
6b0e1402ac

+ 1 - 0
packages/ckeditor5-link/src/link.js

@@ -75,6 +75,7 @@ export default class Link extends Plugin {
  * More information about decorators can be found in the {@link module:link/link~LinkConfig#decorators decorators configuration}
  * reference.
  *
+ * @default false
  * @member {Boolean} module:link/link~LinkConfig#targetDecorator
  */
 

+ 14 - 11
packages/ckeditor5-link/src/linkcommand.js

@@ -30,12 +30,13 @@ export default class LinkCommand extends Command {
 		super( editor );
 
 		/**
-		 * Keeps collection of {@link module:link/utils~ManualDecorator}
-		 * corresponding to {@link module:link/link~LinkConfig#decorators}.
-		 * You can consider it as a model with states of manual decorators added to currently selected link.
+		 * A collection of {@link module:link/utils~ManualDecorator manual decorators}
+		 * corresponding to the {@link module:link/link~LinkConfig#decorators decorator configuration}.
+		 *
+		 * You can consider it a model with states of manual decorators added to currently selected link.
 		 *
 		 * @readonly
-		 * @type {module:utils/collection~Collection}
+		 * @type {module:utils/collection~Collection.<module:link/utils~ManualDecorator>}
 		 */
 		this.manualDecorators = new Collection();
 	}
@@ -69,17 +70,19 @@ 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'`).
+	 * # Decorators and attribute management
+	 *
+	 * This command has an optional argument, which applies or removes model attributes brought by
+	 * {@link module:link/utils~ManualDecorator manual decorators}. Model attribute names correspond to
+	 * decorator {@link module:link/utils~ManualDecorator#id ids} and follow the incremental pattern:
+	 * `'linkManualDecorator0'`, `'linkManualDecorator1'`, `'linkManualDecorator2'`, etc..
 	 *
-	 * More about decorators might be found in {@link module:link/link~LinkConfig#decorators}
+	 * To learn more about link decorators, check out the {@link module:link/link~LinkConfig#decorators `config.link.decorators`}
+	 * documentation.
 	 *
 	 * @fires execute
 	 * @param {String} href Link destination.
-	 * @param {Object} [manualDecoratorIds={}] Keeps information about turned on and off manual decorators applied with command.
+	 * @param {Object} [manualDecoratorIds={}] The information about manual decorator attributes to be applied or removed upon execution.
 	 */
 	execute( href, manualDecoratorIds = {} ) {
 		const model = this.editor.model;

+ 14 - 11
packages/ckeditor5-link/src/linkediting.js

@@ -90,11 +90,13 @@ export default class LinkEditing extends Plugin {
 	}
 
 	/**
-	 * 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}.
+	 * Processes an array of configured {@link module:link/link~LinkDecoratorAutomaticOption automatic decorators}
+	 * and registers a {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher downcast dispatcher}
+	 * for each one of them. Downcast dispatchers are obtained using the
+	 * {@link module:link/utils~AutomaticDecorators#getDispatcher} method.
 	 *
-	 * Method also kept configuration of decorator activated with {@link module:link/link~LinkConfig#targetDecorator}.
+	 * **Note**: This method also activates the automatic external link decorator if enabled via
+	 * {@link module:link/link~LinkConfig#targetDecorator `config.link.targetDecorator`}.
 	 *
 	 * @private
 	 * @param {Array.<module:link/link~LinkDecoratorAutomaticOption>} automaticDecoratorDefinitions
@@ -102,13 +104,12 @@ export default class LinkEditing extends Plugin {
 	_enableAutomaticDecorators( automaticDecoratorDefinitions ) {
 		const editor = this.editor;
 		const automaticDecorators = new AutomaticDecorators();
+
 		// Adds default decorator for external links.
 		if ( editor.config.get( 'link.targetDecorator' ) ) {
 			automaticDecorators.add( {
 				mode: DECORATOR_AUTOMATIC,
-				callback: url => {
-					return EXTERNAL_LINKS_REGEXP.test( url );
-				},
+				callback: url => EXTERNAL_LINKS_REGEXP.test( url ),
 				attributes: {
 					target: '_blank',
 					rel: 'noopener noreferrer'
@@ -117,16 +118,18 @@ export default class LinkEditing extends Plugin {
 		}
 
 		automaticDecorators.add( automaticDecoratorDefinitions );
+
 		if ( automaticDecorators.length ) {
 			editor.conversion.for( 'downcast' ).add( automaticDecorators.getDispatcher() );
 		}
 	}
 
 	/**
-	 * 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}
+	 * Processes an array of configured {@link module:link/link~LinkDecoratorManualOption manual decorators}
+	 * and transforms them into {@link module:link/utils~ManualDecorator} instances and stores them in the
+	 * {@link module:link/linkcommand~LinkCommand#manualDecorators} collection (a model for manual decorators state).
+	 *
+	 * Also registers an {@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.
 	 *