浏览代码

Update docs.

Piotr Jasiun 8 年之前
父节点
当前提交
0894d9283d

+ 5 - 2
packages/ckeditor5-core/src/editor/editor.js

@@ -20,8 +20,11 @@ import ObservableMixin from '@ckeditor/ckeditor5-utils/src/observablemixin';
 import mix from '@ckeditor/ckeditor5-utils/src/mix';
 
 /**
- * Class representing the base of the editor. It is the API all plugins can expect to get when using editor property.
- * Editors implementation (like {@link module:editor-classic/classiceditor~ClassicEditor} or
+ * Class representing the base of the editor. It is the API all plugins can expect to get when using `editor` property.
+ * It should be enough to implement editing part of feature (schema definition, conversion, commands, keystrokes, etc.).
+ * However it does not define editor UI, which is defined in {@link module:core/editor/editorwithui~EditorWithUI}.
+ *
+ * All editors implementation (like {@link module:editor-classic/classiceditor~ClassicEditor} or
  * {@link module:editor-inline/inlineeditor~InlineEditor}) should extend this class. They can add their
  * own methods and properties.
  *

+ 5 - 1
packages/ckeditor5-core/src/editor/editorwithui.jsdoc

@@ -8,7 +8,8 @@
  */
 
 /**
- * Interface that is required for plugins to work (their UI-related part will try to interact with editor UI).
+ * 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 EditorWithUI
  */
@@ -23,5 +24,8 @@
 /**
  * Fired when the editor UI is ready.
  *
+ * Fired after {@link module:core/editor/editor~Editor#event:pluginsReady}, before
+ * {@link module:core/editor/editor~Editor#event:dataReady}.
+ *
  * @event uiReady
  */

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

@@ -8,8 +8,7 @@
  */
 
 /**
- * Mixin provides methods for setting and getting data to/from editor main root element of the model tree
- * using {@link module:core/editor/editor~Editor#data data pipeline}.
+ * Implementation of the {@link module:core/editor/utils/dataapimixin~DataApi}.
  *
  * @mixin DataApiMixin
  * @implements module:core/editor/utils/dataapimixin~DataApi
@@ -33,7 +32,8 @@ const DataApiMixin = {
 export default DataApiMixin;
 
 /**
- * Interface representing classes which mix in {@link module:core/editor/utils/dataapimixin~DataApiMixin}.
+ * Mixin provides methods for setting and getting data to/from editor main root element of the model tree
+ * using {@link module:core/editor/editor~Editor#data data pipeline}.
  *
  * @interface DataApi
  */

+ 2 - 2
packages/ckeditor5-core/src/editor/utils/elementapimixin.js

@@ -11,7 +11,7 @@ import setDataInElement from '@ckeditor/ckeditor5-utils/src/dom/setdatainelement
  */
 
 /**
- * Mixin provides method for setting and getting data from/to element on which editor has been initialized.
+ * Implementation of the {@link module:core/editor/utils/elementapimixin~ElementApi}.
  *
  * @mixin ElementApiMixin
  * @implements module:core/editor/utils/elementapimixin~ElementApi
@@ -35,7 +35,7 @@ const ElementApiMixin = {
 export default ElementApiMixin;
 
 /**
- * Interface representing classes which mix in {@link module:core/editor/utils/elementapimixin~ElementApiMixin}.
+ * Mixin provides method for setting and getting data from/to element on which editor has been initialized.
  *
  * @interface ElementApi
  */

+ 10 - 0
packages/ckeditor5-core/src/plugin.js

@@ -24,6 +24,16 @@ export default class Plugin {
 		/**
 		 * The editor instance.
 		 *
+		 * Note that most editors implements {@link module:core/editor/editorwithui~EditorWithUI} interface in addition
+		 * to the base {@link module:core/editor/editor~Editor} interface. However, editors with external UI
+		 * (i.e. Bootstrap based) or headless editor may not implement {@link module:core/editor/editorwithui~EditorWithUI}
+		 * interface.
+		 *
+		 * Because of above, to make plugins more universal, it is recommended to split features into:
+		 *  - "Editing" part which use only {@link module:core/editor/editor~Editor} interface,
+		 *  - "UI" part which use both {@link module:core/editor/editor~Editor} interface and
+		 *  {@link module:core/editor/editorwithui~EditorWithUI} interface.
+		 *
 		 * @readonly
 		 * @member {module:core/editor/editor~Editor} #editor
 		 */