Ver código fonte

API docs fixes.

Szymon Kupś 9 anos atrás
pai
commit
33f772e6c2

+ 45 - 40
packages/ckeditor5-clipboard/src/clipboard.js

@@ -3,6 +3,10 @@
  * For licensing, see LICENSE.md.
  */
 
+/**
+ * @module clipboard/clipboard
+ */
+
 import Plugin from '../core/plugin.js';
 
 import ClipboardObserver from './clipboardobserver.js';
@@ -22,24 +26,24 @@ import HtmlDataProcessor from '../engine/dataprocessor/htmldataprocessor.js';
  * before it gets inserted into the editor. The pipeline consists of two events on which
  * the features can listen in order to modify or totally override the default behavior.
  *
- * ### On {@link engine.view.Document#paste}
+ * ### On {@link module:engine/view/document~Document#event:paste}
  *
  * The default action is to:
  *
  * 1. get HTML or plain text from the clipboard,
  * 2. prevent the default action of the native `paste` event,
- * 3. fire {@link engine.view.Document#clipboardInput} with the clipboard data parsed to
- * a {@link engine.view.DocumentFragment view document fragment}.
+ * 3. fire {@link module:engine/view/document~Document#event:clipboardInput} with the clipboard data parsed to
+ * a {@link module:engine/view/documentfragment~DocumentFragment view document fragment}.
  *
  * This action is performed by a low priority listener, so it can be overridden by a normal one
  * when a deeper change in pasting behavior is needed. For example, a feature which wants to differently read
- * data from the clipboard (the {@link clipboard.DataTransfer `DataTransfer`}).
+ * data from the clipboard (the {@link module:clipboard/datatransfer~DataTransfer `DataTransfer`}).
  * should plug a listener at this stage.
  *
- * ### On {@link engine.view.Document#clipboardInput}
+ * ### On {@link module:engine/view/document~Document#event:clipboardInput}
  *
- * The default action is to insert the content (`data.content`, represented by a {@link engine.view.DocumentFragment})
- * to an editor if the data is not empty.
+ * The default action is to insert the content (`data.content`, represented by a
+ * {@link module:engine/view/documentfragment~DocumentFragment}) to an editor if the data is not empty.
  *
  * This action is performed by a low priority listener, so it can be overridden by a normal one.
  *
@@ -65,26 +69,26 @@ import HtmlDataProcessor from '../engine/dataprocessor/htmldataprocessor.js';
  * The output pipeline is the equivalent of the input pipeline but for the copy and cut operations.
  * It allows to process the content which will be then put into the clipboard or to override the whole process.
  *
- * ### On {@link engine.view.Document#copy} and {@link engine.view.Document#cut}
+ * ### On {@link module:engine/view/document~Document#event:copy} and {@link module:engine/view/document~Document#event:cut}
  *
  * The default action is to:
  *
- * 1. {@link engine.controller.DataController#getSelectedContent get selected content} from the editor,
+ * 1. {@link module:engine/controller/datacontroller~DataController#getSelectedContent get selected content} from the editor,
  * 2. prevent the default action of the native `copy` or `cut` event,
- * 3. fire {@link engine.view.Document#clipboardOutput} with a clone of the selected content
- * converted to a {@link engine.view.DocumentFragment view document fragment}.
+ * 3. fire {@link module:engine/view/document~Document#event:clipboardOutput} with a clone of the selected content
+ * converted to a {@link module:engine/view/documentfragment~DocumentFragment view document fragment}.
  *
- * ### On {@link engine.view.Document#clipboardOutput}
+ * ### On {@link module:engine/view/document~Document#event:clipboardOutput}
  *
- * The default action is to put the content (`data.content`, represented by a {@link engine.view.DocumentFragment})
- * to the clipboard as HTML. In case of the cut operation, the selected content is also deleted from the editor.
+ * The default action is to put the content (`data.content`, represented by a
+ * {@link module:engine/view/documentfragment~DocumentFragment}) to the clipboard as HTML. In case of the cut operation,
+ * the selected content is also deleted from the editor.
  *
  * This action is performed by a low priority listener, so it can be overridden by a normal one.
  *
  * At this stage the copied/cut content can be processed by the features.
  *
- * @memberOf clipboard
- * @extends core.Plugin
+ * @extends module:core.plugin~Plugin
  */
 export default class Clipboard extends Plugin {
 	/**
@@ -99,7 +103,7 @@ export default class Clipboard extends Plugin {
 		 * Data processor used to convert pasted HTML to a view structure.
 		 *
 		 * @private
-		 * @member {engine.dataProcessor.HtmlDataProcessor} clipboard.Clipboard#_htmlDataProcessor
+		 * @member {module:engine/dataprocessor/htmldataprocessor~HtmlDataProcessor} #_htmlDataProcessor
 		 */
 		this._htmlDataProcessor = new HtmlDataProcessor();
 
@@ -172,66 +176,67 @@ export default class Clipboard extends Plugin {
 /**
  * Fired with a content which comes from the clipboard (was pasted or dropped) and
  * should be processed in order to be inserted into the editor.
- * It's part of the {@link clipboard.Clipboard "clipboard pipeline"}.
+ * It's part of the {@link module:clipboard/clipboard~Clipboard "clipboard pipeline"}.
  *
- * @see clipboard.ClipboardObserver
- * @see clipboard.Clipboard
- * @event engine.view.Document#clipboardInput
- * @param {engine.view.observer.ClipboardInputEventData} data Event data.
+ * @see module:clipboard/clipboardobserver~ClipboardObserver
+ * @see module:clipboard/clipboard~Clipboard
+ * @event module:engine/view/document~Document#event:clipboardInput
+ * @param {module:clipboard/clipboard~ClipboardInputEventData} data Event data.
  */
 
 /**
- * The value of the {@link engine.view.Document#clipboardInput} event.
+ * The value of the {@link module:engine/view/document~Document#event:clipboardInput} event.
  *
- * @class engine.view.observer.ClipboardInputEventData
+ * @class module:clipboard/clipboard~ClipboardInputEventData
  */
 
 /**
  * Data transfer instance.
  *
  * @readonly
- * @member {clipboard.DataTransfer} engine.view.observer.ClipboardInputEventData#dataTransfer
+ * @member {module:clipboard/datatransfer~DataTransfer} module:clipboard/clipboard~ClipboardInputEventData#dataTransfer
  */
 
 /**
  * Content to be inserted into the editor. It can be modified by the event listeners.
- * Read more about the clipboard pipelines in {@link clipboard.Clipboard}.
+ * Read more about the clipboard pipelines in {@link module:clipboard/clipboard~Clipboard}.
  *
- * @member {engine.view.DocumentFragment} engine.view.observer.ClipboardInputEventData#content
+ * @member {module:engine/view/documentfragment~DocumentFragment} module:clipboard/clipboard~ClipboardInputEventData#content
  */
 
 /**
- * Fired on {@link envine.view.Document#copy} and {@link envine.view.Document#cut} with a copy of selected content.
- * The content can be processed before it ends up in the clipboard. It's part of the {@link clipboard.Clipboard "clipboard pipeline"}.
- *
- * @see clipboard.ClipboardObserver
- * @see clipboard.Clipboard
- * @event engine.view.Document#clipboardOutput
- * @param {engine.view.observer.ClipboardOutputEventData} data Event data.
+ * Fired on {@link module:engine/view/document~Document#event:copy} and {@link module:engine/view/document~Document#event:cut}
+ * with a copy of selected content. The content can be processed before it ends up in the clipboard.
+ * It's part of the {@link module:clipboard/clipboard~Clipboard "clipboard pipeline"}.
+ *
+ * @see module:clipboard/clipboardobserver~ClipboardObserver
+ * @see module:clipboard/clipboard~Clipboard
+ * @event module:engine/view/document~Document#event:clipboardOutput
+ * @param {module:clipboard/clipboard/ClipboardOutputEventData} data Event data.
  */
 
 /**
- * The value of the {@link engine.view.Document#clipboardOutput} event.
+ * The value of the {@link module:engine/view/document~Document#event:clipboardOutput} event.
  *
- * @class engine.view.observer.ClipboardOutputEventData
+ * @class module:clipboard/clipboard/ClipboardOutputEventData
  */
 
 /**
  * Data transfer instance.
  *
  * @readonly
- * @member {clipboard.DataTransfer} engine.view.observer.ClipboardOutputEventData#dataTransfer
+ * @member {module:clipboard/datatransfer~DataTransfer} module:clipboard/clipboard~ClipboardOutputEventData#dataTransfer
  */
 
 /**
  * Content to be put into the clipboard. It can be modified by the event listeners.
- * Read more about the clipboard pipelines in {@link clipboard.Clipboard}.
+ * Read more about the clipboard pipelines in {@link module:clipboard/clipboard~Clipboard}.
  *
- * @member {engine.view.DocumentFragment} engine.view.observer.ClipboardOutputEventData#content
+ * @member {module:engine/view/documentfragment~DocumentFragment} module:clipboard/clipboard~ClipboardOutputEventData#content
  */
 
 /**
  * Whether the event was triggered by copy or cut operation.
  *
- * @member {'copy'|'cut'} engine.view.observer.ClipboardOutputEventData#method
+ * @member {'copy'|'cut'} module:clipboard/clipboard~ClipboardOutputEventData#method
  */

+ 35 - 31
packages/ckeditor5-clipboard/src/clipboardobserver.js

@@ -3,17 +3,20 @@
  * For licensing, see LICENSE.md.
  */
 
+/**
+ * @module clipboard/clipboardobserver
+ */
+
 import DomEventObserver from '../engine/view/observer/domeventobserver.js';
 import DataTransfer from './datatransfer.js';
 
 /**
- * {@link engine.view.Document#paste Paste} event observer.
+ * {@link module:engine/view/document~Document#event:paste Paste} event observer.
  *
- * Note that this observer is not available by default. To make it available it needs to be added to {@link engine.view.Document}
- * by the {@link engine.view.Document#addObserver} method.
+ * Note that this observer is not available by default. To make it available it needs to be added to
+ * {@link module:engine/view/document~Document} by the {@link module:engine/view/document~Document#addObserver} method.
  *
- * @memberOf clipboard
- * @extends engine.view.observer.DomEventObserver
+ * @extends module:engine/view/observer/domeventobserver~DomEventObserver
  */
 export default class ClipboardObserver extends DomEventObserver {
 	constructor( doc ) {
@@ -32,57 +35,58 @@ export default class ClipboardObserver extends DomEventObserver {
 /**
  * Fired when user pasted content into one of the editables.
  *
- * Introduced by {@link clipboard.ClipboardObserver}.
+ * Introduced by {@link module:clipboard/clipboardobserver~ClipboardObserver}.
  *
- * Note that this event is not available by default. To make it available {@link clipboard.ClipboardObserver} needs to be added
- * to {@link engine.view.Document} by the {@link engine.view.Document#addObserver} method.
- * It's done by the {@link clipboard.Clipboard} feature. If it's not loaded, it must be done manually.
+ * Note that this event is not available by default. To make it available {@link module:clipboard/clipboardobserver~ClipboardObserver}
+ * needs to be added to {@link module:engine/view/document~Document} by the {@link module:engine/view/document~Document#addObserver} method.
+ * It's done by the {@link module:clipboard/clipboard~Clipboard} feature. If it's not loaded, it must be done manually.
  *
- * @see clipboard.ClipboardObserver
- * @event engine.view.Document#paste
- * @param {engine.view.observer.ClipboardEventData} data Event data.
+ * @see module:clipboard/clipboardobserver~ClipboardObserver
+ * @event module:engine/view/document~Document#event:paste
+ * @param {module:clipboard/clipboardobserver~ClipboardEventData} data Event data.
  */
 
 /**
  * Fired when user copied content from one of the editables.
  *
- * Introduced by {@link clipboard.ClipboardObserver}.
+ * Introduced by {@link module:clipboard/clipboardobserver~ClipboardObserver}.
  *
- * Note that this event is not available by default. To make it available {@link clipboard.ClipboardObserver} needs to be added
- * to {@link engine.view.Document} by the {@link engine.view.Document#addObserver} method.
- * It's done by the {@link clipboard.Clipboard} feature. If it's not loaded, it must be done manually.
+ * Note that this event is not available by default. To make it available {@link module:clipboard/clipboardobserver~ClipboardObserver}
+ * needs to be added to {@link module:engine/view/document~Document} by the {@link module:engine/view/document~Document#addObserver} method.
+ * It's done by the {@link module:clipboard/clipboard~Clipboard} feature. If it's not loaded, it must be done manually.
  *
- * @see clipboard.ClipboardObserver
- * @event engine.view.Document#copy
- * @param {engine.view.observer.ClipboardEventData} data Event data.
+ * @see module:clipboard/clipboardobserver~ClipboardObserver
+ * @event module:engine/view/document~Document#event:copy
+ * @param {module:clipboard/clipboardobserver~ClipboardEventData} data Event data.
  */
 
 /**
  * Fired when user cut content from one of the editables.
  *
- * Introduced by {@link clipboard.ClipboardObserver}.
+ * Introduced by {@link module:clipboard/clipboardobserver~ClipboardObserver}.
  *
- * Note that this event is not available by default. To make it available {@link clipboard.ClipboardObserver} needs to be added
- * to {@link engine.view.Document} by the {@link engine.view.Document#addObserver} method.
- * It's done by the {@link clipboard.Clipboard} feature. If it's not loaded, it must be done manually.
+ * Note that this event is not available by default. To make it available {@link module:clipboard/clipboardobserver~ClipboardObserver}
+ * needs to be added to {@link module:engine/view/document~Document} by the {@link module:engine/view/document~Document#addObserver} method.
+ * It's done by the {@link module:clipboard/clipboard~Clipboard} feature. If it's not loaded, it must be done manually.
  *
- * @see clipboard.ClipboardObserver
- * @event engine.view.Document#cut
- * @param {engine.view.observer.ClipboardEventData} data Event data.
+ * @see module:clipboard/clipboardobserver~ClipboardObserver
+ * @event module:engine/view/document~Document#event:cut
+ * @param {module:clipboard/clipboardobserver~ClipboardEventData} data Event data.
  */
 
 /**
- * The value of the {@link engine.view.Document#paste}, {@link engine.view.Document#copy} and {@link engine.view.Document#cut} events.
+ * The value of the {@link module:engine/view/document~Document#event:paste},
+ * {@link module:engine/view/document~Document#event:copy} and {@link module:engine/view/document~Document#event:cut} events.
  *
- * In order to access clipboard data use {@link #dataTransfer}.
+ * In order to access clipboard data use `dataTransfer` property.
  *
- * @class engine.view.observer.ClipboardEventData
- * @extends engine.view.observer.DomEventData
+ * @class module:clipboard/clipboardobserver~ClipboardEventData
+ * @extends module:engine/view/observer/domeventdata~DomEventData
  */
 
 /**
  * Data transfer instance.
  *
  * @readonly
- * @member {clipboard.DataTransfer} engine.view.observer.ClipboardEventData#dataTransfer
+ * @member {module:clipboard/datatransfer~DataTransfer} module:clipboard/clipboardobserver~ClipboardEventData#dataTransfer
  */

+ 5 - 3
packages/ckeditor5-clipboard/src/datatransfer.js

@@ -4,9 +4,11 @@
  */
 
 /**
+ * @module clipboard/datatransfer
+ */
+
+/**
  * Facade over the native [`DataTransfer`](https://developer.mozilla.org/en-US/docs/Web/API/DataTransfer) object.
- *
- * @memberOf clipboard
  */
 export default class DataTransfer {
 	constructor( nativeDataTransfer ) {
@@ -14,7 +16,7 @@ export default class DataTransfer {
 		 * The native DataTransfer object.
 		 *
 		 * @private
-		 * @member {DataTransfer} clipboard.DataTransfer#_native
+		 * @member {DataTransfer} #_native
 		 */
 		this._native = nativeDataTransfer;
 	}

+ 4 - 1
packages/ckeditor5-clipboard/src/utils/normalizeclipboarddata.js

@@ -4,9 +4,12 @@
  */
 
 /**
+ * @module clipboard/utils/normalizeclipboarddata
+ */
+
+/**
  * Removes some popular browser quirks out of the clipboard data (HTML).
  *
- * @function clipboard.utils.normalizeClipboardData
  * @param {String} data The HTML data to normalize.
  * @returns {String} Normalized HTML.
  */

+ 4 - 1
packages/ckeditor5-clipboard/src/utils/plaintexttohtml.js

@@ -4,9 +4,12 @@
  */
 
 /**
+ * @module clipboard/utils/plaintexttohtml
+ */
+
+/**
  * Converts plain text to its HTML-ized version.
  *
- * @function clipboard.utils.plainTextToHtml
  * @param {String} text The plain text to convert.
  * @returns {String} HTML generated from the plain text.
  */