Browse Source

Docs: Improved few more interfaces. [skip ci]

Piotrek Koszuliński 7 years ago
parent
commit
498fa91a5f

+ 10 - 3
packages/ckeditor5-core/src/editor/editorwithui.jsdoc

@@ -8,8 +8,15 @@
  */
 
 /**
- * Interface defining UI part of the editor. Most editor (like {@link module:editor-classic/classiceditor~ClassicEditor} or
- * {@link module:editor-inline/inlineeditor~InlineEditor}) implements this interface, however it is not required to do so. Editors with external UI (i.e. Bootstrap based) or headless editor may not implement this interface. Keep it in mind when developing features.
+ * Interface defining a type of {@link module:core/editor/editor~Editor editor} which has a UI.
+ *
+ * Most editors (like {@link module:editor-classic/classiceditor~ClassicEditor} or
+ * {@link module:editor-inline/inlineeditor~InlineEditor}) implement this interface, however it is not required to do so.
+ *
+ * Editors with external UI (i.e. Bootstrap based) or headless editor may not implement this interface.
+ * When developing editor features you can consider this by splitting them into two parts – the "editing" part,
+ * which bases on {@link module:core/editor/editor~Editor} itself and the UI part which bases on the this interface.
+ * This will make your features compatible with more types of editors.
  *
  * @interface EditorWithUI
  */
@@ -24,7 +31,7 @@
 /**
  * Fired when the editor UI is ready.
  *
- * Fired after {@link module:core/editor/editor~Editor#event:pluginsReady}, before
+ * Fired after {@link module:core/editor/editor~Editor#event:pluginsReady} and before
  * {@link module:core/editor/editor~Editor#event:dataReady}.
  *
  * @event uiReady

+ 25 - 3
packages/ckeditor5-core/src/editor/utils/dataapimixin.js

@@ -32,21 +32,43 @@ const DataApiMixin = {
 export default DataApiMixin;
 
 /**
- * Interface for setting and getting data to/from the editor's main root element
+ * Interface defining an editor methods for setting and getting data to/from the editor's main root element
  * using the {@link module:core/editor/editor~Editor#data data pipeline}.
  *
+ * This interface is not part of the {@link module:core/editor/editor~Editor} class because one may want to implement
+ * an editor with multiple root elements, in which case the methods for setting/getting data will need to be implemented
+ * differently.
+ *
  * @interface DataApi
  */
 
 /**
- * Sets the data in the editor's main root.
+ * Sets the data in the editor.
+ *
+ *		editor.setData( '<p>This is editor!</p>' );
+ *
+ * By default the editor accepts HTML. This can be controlled by injecting a different data processor.
+ * See {@glink features/markdown Markdown output} guide for more details.
+ *
+ * Note: Not only is the format of the data configurable, but the type of the `setData()`'s parameter does not
+ * have to be a string either. You can e.g. accept an object or a DOM `DocumentFragment` if you consider this
+ * the right format for you.
  *
  * @method #setData
  * @param {String} data Input data.
  */
 
 /**
- * Gets the data from the editor's main root.
+ * Gets the data from the editor.
+ *
+ *		editor.getData(); // -> '<p>This is editor!</p>'
+ *
+ * By default the editor outputs HTML. This can be controlled by injecting a different data processor.
+ * See {@glink features/markdown Markdown output} guide for more details.
+ *
+ * Note: Not only is the format of the data configurable, but the type of the `getData()`'s return value does not
+ * have to be a string either. You can e.g. return an object or a DOM `DocumentFragment`  if you consider this
+ * the right format for you.
  *
  * @method #getData
  * @returns {String} Output data.