8
0
Просмотр исходного кода

Update the docs for mention ui.

Maciej Gołaszewski 6 лет назад
Родитель
Сommit
1bd6c44a17

+ 53 - 0
packages/ckeditor5-mention/src/mentionui.js

@@ -216,18 +216,40 @@ export default class MentionUI extends Plugin {
 		return mentionsView;
 	}
 
+	/**
+	 * Returns item renderer for marker.
+	 *
+	 * @private
+	 * @param {String} marker
+	 * @returns {Function|null}
+	 */
 	_getItemRenderer( marker ) {
 		const { itemRenderer } = this._mentionsConfigurations.get( marker );
 
 		return itemRenderer;
 	}
 
+	/**
+	 * Returns a promise that resolves with autocomplete items for given text.
+	 *
+	 * @param {String} marker
+	 * @param {String} feedText
+	 * @return {Promise<module:mention/mention~MentionFeedItem>}
+	 * @private
+	 */
 	_getFeed( marker, feedText ) {
 		const { feedCallback } = this._mentionsConfigurations.get( marker );
 
 		return Promise.resolve().then( () => feedCallback( feedText ) );
 	}
 
+	/**
+	 * Registers a text watcher for marker.
+	 *
+	 * @private
+	 * @param {String} marker
+	 * @returns {TextWatcher}
+	 */
 	_setupTextWatcherForFeed( marker ) {
 		const editor = this.editor;
 
@@ -272,6 +294,13 @@ export default class MentionUI extends Plugin {
 		return watcher;
 	}
 
+	/**
+	 * Returns registered text watcher for marker.
+	 *
+	 * @private
+	 * @param {String} marker
+	 * @returns {TextWatcher}
+	 */
 	_getWatcher( marker ) {
 		const { watcher } = this._mentionsConfigurations.get( marker );
 
@@ -299,6 +328,14 @@ export default class MentionUI extends Plugin {
 		this.panelView.hide();
 	}
 
+	/**
+	 * Renders the single item in autocomplete list.
+	 *
+	 * @private
+	 * @param {module:mention/mention~MentionFeedItem} item
+	 * @param {String} marker
+	 * @returns {module:ui/button/buttonview~ButtonView|module:mention/ui/domwrapperview~DomWrapperView}
+	 */
 	_renderItem( item, marker ) {
 		const editor = this.editor;
 
@@ -386,18 +423,30 @@ function getBalloonPanelPositions() {
 	];
 }
 
+// Creates a regex pattern for marker.
+//
+// @param {String} marker
+// @returns {String}
 function createPattern( marker ) {
 	const numberOfCharacters = '*';
 
 	return `(^| )(${ marker })([_a-zA-Z0-9À-ž]${ numberOfCharacters }?)$`;
 }
 
+// Creates a test callback for marker to be used in text watcher instance.
+//
+// @param {String} marker
+// @returns {Function}
 function createTestCallback( marker ) {
 	const regExp = new RegExp( createPattern( marker ) );
 
 	return text => regExp.test( text );
 }
 
+// Creates a text watcher matcher for marker.
+//
+// @param {String} marker
+// @returns {Function}
 function createTextMatcher( marker ) {
 	const regExp = new RegExp( createPattern( marker ) );
 
@@ -422,6 +471,10 @@ function createFeedCallback( feedItems ) {
 	};
 }
 
+// Checks if given key code is handled by the mention ui.
+//
+// @param {Number}
+// @returns {Boolean}
 function isHandledKey( keyCode ) {
 	const handledKeyCodes = [
 		keyCodes.arrowup,

+ 26 - 3
packages/ckeditor5-mention/src/textwatcher.js

@@ -12,22 +12,39 @@ import EmitterMixin from '@ckeditor/ckeditor5-utils/src/emittermixin';
 
 /**
  * Text watcher feature.
+ * @private
  */
 export default class TextWatcher {
-	constructor( editor, callbackOrRegex, textMatcher ) {
+	/**
+	 * Creates a text watcher instance.
+	 * @param {module:core/editor/editor~Editor} editor
+	 * @param {Function} testCallback Function used to match the text.
+	 * @param {Function} textMatcherCallback Function used to process matched text.
+	 */
+	constructor( editor, testCallback, textMatcherCallback ) {
 		this.editor = editor;
-		this.testCallback = callbackOrRegex;
-		this.textMatcher = textMatcher;
+		this.testCallback = testCallback;
+		this.textMatcher = textMatcherCallback;
 
 		this.hasMatch = false;
 
 		this._startListening();
 	}
 
+	/**
+	 * Last matched text.
+	 *
+	 * @property {String}
+	 */
 	get last() {
 		return this._getText();
 	}
 
+	/**
+	 * Starts listening the editor for typing & selection events.
+	 *
+	 * @private
+	 */
 	_startListening() {
 		const editor = this.editor;
 
@@ -66,6 +83,12 @@ export default class TextWatcher {
 		} );
 	}
 
+	/**
+	 * Returns the text before the caret from the current selection block.
+	 *
+	 * @returns {String|undefined} Text from block or undefined if selection is not collapsed.
+	 * @private
+	 */
 	_getText() {
 		const editor = this.editor;
 		const selection = editor.model.document.selection;