From d0da6549713965e58b110726c58c127d59c02e3d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Piotrek=20Koszuli=C5=84ski?= <pkoszulinski@gmail.com>
Date: Tue, 3 Jul 2018 18:14:34 +0200
Subject: [PATCH] More docs polish.

---
 src/decouplededitor.js       | 30 ++++++++++++++----------------
 src/decouplededitoruiview.js |  3 ++-
 2 files changed, 16 insertions(+), 17 deletions(-)

diff --git a/src/decouplededitor.js b/src/decouplededitor.js
index 74baaaf..e252f03 100644
--- a/src/decouplededitor.js
+++ b/src/decouplededitor.js
@@ -57,25 +57,15 @@ export default class DecoupledEditor extends Editor {
 	 * {@link module:editor-decoupled/decouplededitor~DecoupledEditor.create `DecoupledEditor.create()`} method instead.
 	 *
 	 * @protected
-	 * @param {HTMLElement|String} sourceElementOrData The DOM element that serves as an editable.
-	 * The data will be loaded from it and loaded back to it once the editor is destroyed.
-	 * Alternatively, a data string to be loaded into the editor.
+	 * @param {HTMLElement|String} sourceElementOrData The DOM element that will be the source for the created editor
+	 * (on which the editor will be initialized) or initial data for the editor. For more information see
+	 * {@link module:editor-balloon/ballooneditor~BalloonEditor.create `BalloonEditor.create()`}.
 	 * @param {module:core/editor/editorconfig~EditorConfig} config The editor configuration.
 	 */
 	constructor( sourceElementOrData, config ) {
 		super( config );
 
 		if ( isElement( sourceElementOrData ) ) {
-			/**
-			 * The element used as an editable. The data will be loaded from it and loaded back to
-			 * it once the editor is destroyed.
-			 *
-			 * **Note:** The property is available only when such element has been passed
-			 * to the {@link #constructor}.
-			 *
-			 * @readonly
-			 * @member {HTMLElement}
-			 */
 			this.sourceElement = sourceElementOrData;
 		}
 
@@ -90,6 +80,8 @@ export default class DecoupledEditor extends Editor {
 	 * @inheritDoc
 	 */
 	get element() {
+		// This editor has no single "main UI element". Its editable and toolbar are exposed separately and need
+		// to be added to the DOM manually by the consumer.
 		return null;
 	}
 
@@ -185,9 +177,15 @@ export default class DecoupledEditor extends Editor {
 	 *				console.error( err.stack );
 	 *			} );
 	 *
-	 * @param {HTMLElement|String} sourceElementOrData The DOM element that serves as an editable.
-	 * The data will be loaded from it and loaded back to it once the editor is destroyed.
-	 * Alternatively, a data string to be loaded into the editor.
+	 * @param {HTMLElement|String} sourceElementOrData The DOM element that will be the source for the created editor
+	 * (on which the editor will be initialized) or initial data for the editor.
+	 *
+	 * If a source element is passed, then its contents will be automatically
+	 * {@link module:editor-decoupled/decouplededitor~DecoupledEditor#setData loaded} to the editor on startup and the element
+	 * itself will be used as the editor's editable element.
+	 *
+	 * If data is provided, then `editor.ui.view.editable.element` will be created automatically and needs to be added
+	 * to the DOM manually.
 	 * @param {module:core/editor/editorconfig~EditorConfig} config The editor configuration.
 	 * @returns {Promise} A promise resolved once the editor is ready.
 	 * The promise returns the created {@link module:editor-decoupled/decouplededitor~DecoupledEditor} instance.
diff --git a/src/decouplededitoruiview.js b/src/decouplededitoruiview.js
index c7ef927..00688d9 100644
--- a/src/decouplededitoruiview.js
+++ b/src/decouplededitoruiview.js
@@ -28,7 +28,8 @@ export default class DecoupledEditorUIView extends EditorUIView {
 	 * Creates an instance of the decoupled editor UI view.
 	 *
 	 * @param {module:utils/locale~Locale} locale The {@link module:core/editor/editor~Editor#locale} instance.
-	 * @param {HTMLElement} [editableElement] The DOM element to be used as editable.
+	 * @param {HTMLElement} [editableElement] The editable element. If not specified, it will be automatically created by
+	 * {@link module:ui/editableui/editableuiview~EditableUIView}. Otherwise, the given element will be used.
 	 */
 	constructor( locale, editableElement ) {
 		super( locale );