浏览代码

Docs: API docs corrected. [skip ci]

Anna Tomanek 7 年之前
父节点
当前提交
a274899b99

+ 9 - 9
packages/ckeditor5-core/src/editor/editorconfig.jsdoc

@@ -10,7 +10,7 @@
 /**
  * CKEditor configuration options.
  *
- * The object defining editor configuration can be passed when initializing the editor:
+ * An object defining the editor configuration can be passed when initializing the editor:
  *
  *		EditorClass
  *			.create( {
@@ -34,7 +34,7 @@
  * The list of plugins to load.
  *
  * If you use an {@glink builds/guides/overview editor build} you can define the list of plugins to load
- * using names of plugins which are available:
+ * using the names of plugins that are available:
  *
  *		const config = {
  *			plugins: [ 'Bold', 'Italic', 'Typing', 'Enter', ... ]
@@ -76,7 +76,7 @@
  */
 
 /**
- * Editor toolbar configuration.
+ * The editor toolbar configuration.
  *
  * Simple format (specifies only toolbar items):
  *
@@ -96,7 +96,7 @@
  *
  * Options which can be set using the extended format:
  *
- * * **`toolbar.items`** – Array of toolbar items names. The components (buttons, dropdowns, etc.) which can be used
+ * * **`toolbar.items`** – An array of toolbar item names. The components (buttons, dropdowns, etc.) which can be used
  * as toolbar items are defined in `editor.ui.componentFactory` and can be listed using the following snippet:
  *
  *		Array.from( editor.ui.componentFactory.names() );
@@ -105,20 +105,20 @@
  *
  *		toolbar: [ 'bold', 'italic', '|', 'undo', 'redo' ]
  *
- * * **`toolbar.viewportTopOffset`**  The offset (in pixels) from the top of the viewport used when positioning a sticky toolbar.
+ * * **`toolbar.viewportTopOffset`** – The offset (in pixels) from the top of the viewport used when positioning a sticky toolbar.
  * Useful when a page with which the editor is being integrated has some other sticky or fixed elements
- * (e.g. the top menu). Thanks to setting the toolbar offset the toolbar won't be positioned underneath or above the page's UI.
+ * (e.g. the top menu). Thanks to setting the toolbar offset the toolbar will not be positioned underneath or above the page's UI.
  *
  * @member {Array.<String>|Object} module:core/editor/editorconfig~EditorConfig#toolbar
  */
 
 /**
- * Editor UI's language.
+ * The editor UI's language.
  *
  * The language code is defined in the [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) standard.
  * CKEditor 5 currently supports around 20 languages and the number is growing.
  *
- * Note: You don't have to specify this option if your build is optimized for one language or if it's the default language
+ * Note: You do not have to specify this option if your build is optimized for one language or if it is the default language
  * (English is the default language for CDN builds).
  *
  * Simple usage:
@@ -134,7 +134,7 @@
  *				console.error( error );
  *			} );
  *
- * After this step you need to attach the corresponding translation file. Translation files are available at CDN for predefined builds:
+ * After this step you need to attach the corresponding translation file. Translation files are available on CDN for predefined builds:
  *		`<script src="https://cdn.ckeditor.com/ckeditor5/[version.number]/[distribution]/lang/[lang].js"></script>`
  *
  * But you can add them manually by coping from the `node_modules/@ckeditor/ckeditor5-build-[name]/build/lang/[lang].js'`.

+ 11 - 11
packages/ckeditor5-core/src/editor/editorwithui.jsdoc

@@ -11,34 +11,34 @@
  * 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.
+ * {@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.
+ * Editors with an external UI (i.e. Bootstrap-based) or a 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 this interface.
  * This will make your features compatible with more types of editors.
  *
  * @interface EditorWithUI
  */
 
 /**
- * Editor UI instance.
+ * The editor UI instance.
  *
  * @readonly
  * @member {module:core/editor/editorui~EditorUI} #ui
  */
 
  /**
-  * The main (outermost) DOM element of the editor's UI.
+  * The main (outermost) DOM element of the editor UI.
   *
-  * For example, in the {@link module:editor-classic/classiceditor~ClassicEditor} it is a `<div>` which
-  * wraps the editable element and the toolbar. In the {@link module:editor-inline/inlineeditor~InlineEditor}
-  * it is the editable element itself (as there is no other wrapper). However, in the
+  * For example, in {@link module:editor-classic/classiceditor~ClassicEditor} it is a `<div>` which
+  * wraps the editable element and the toolbar. In {@link module:editor-inline/inlineeditor~InlineEditor}
+  * it is the editable element itself (as there is no other wrapper). However, in
   * {@link module:editor-decoupled/decouplededitor~DecoupledEditor} it is set to `null` because this editor does not
   * come with a single "main" HTML element (its editable element and toolbar are separate).
   *
-  * This property can be understood as a shorthand for retrieving the element which specific editor integration
-  * considers to be its main DOM element. There are always other ways to access these elements too
+  * This property can be understood as a shorthand for retrieving the element that a specific editor integration
+  * considers to be its main DOM element. There are always other ways to access these elements, too
   * (e.g. via {@link #ui `editor.ui`}).
   *
   * @readonly

+ 5 - 5
packages/ckeditor5-core/src/editor/utils/attachtoform.js

@@ -11,21 +11,21 @@ import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
  */
 
 /**
- * Checks if editor is initialized on textarea element that belongs to a form. If yes - updates editor's element
- * contents before submitting the form.
+ * Checks if the editor is initialized on a `<textarea>` element that belongs to a form. If yes, it updates the editor's element
+ * content before submitting the form.
  *
- * This helper requires {@link module:core/editor/utils/elementapimixin~ElementApi ElementApi interface}.
+ * This helper requires the {@link module:core/editor/utils/elementapimixin~ElementApi ElementApi interface}.
  *
  * @param {module:core/editor/editor~Editor} editor Editor instance.
  */
 export default function attachToForm( editor ) {
 	if ( !isFunction( editor.updateSourceElement ) ) {
 		/**
-		 * {@link module:core/editor/utils/elementapimixin~ElementApi ElementApi interface} is required.
+		 * The {@link module:core/editor/utils/elementapimixin~ElementApi ElementApi interface} is required.
 		 *
 		 * @error attachtoform-missing-elementapi-interface
 		 */
-		throw new CKEditorError( 'attachtoform-missing-elementapi-interface: ElementApi interface is required.' );
+		throw new CKEditorError( 'attachtoform-missing-elementapi-interface: The ElementApi interface is required.' );
 	}
 
 	const sourceElement = editor.sourceElement;

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

@@ -32,11 +32,11 @@ const DataApiMixin = {
 export default DataApiMixin;
 
 /**
- * Interface defining an editor methods for setting and getting data to/from the editor's main root element
+ * Interface defining editor methods for setting and getting data to and 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
+ * This interface is not a 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 and getting data will need to be implemented
  * differently.
  *
  * @interface DataApi
@@ -48,7 +48,7 @@ export default DataApiMixin;
  *		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.
+ * See the {@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
@@ -64,7 +64,7 @@ export default DataApiMixin;
  *		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.
+ * See the {@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

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

@@ -40,7 +40,7 @@ const ElementApiMixin = {
 export default ElementApiMixin;
 
 /**
- * Interface describing an editor which replaced a DOM element (was "initialized on an element").
+ * Interface describing an editor that replaced a DOM element (was "initialized on an element").
  *
  * Such an editor should provide a method to
  * {@link module:core/editor/utils/elementapimixin~ElementApi#updateSourceElement update the replaced element with the current data}.

+ 11 - 13
packages/ckeditor5-core/src/plugincollection.js

@@ -83,11 +83,11 @@ export default class PluginCollection {
 	 * Loads a set of plugins and adds them to the collection.
 	 *
 	 * @param {Array.<Function|String>} plugins An array of {@link module:core/plugin~PluginInterface plugin constructors}
-	 * or {@link module:core/plugin~PluginInterface.pluginName plugin names}. The second option (names) work only if
+	 * or {@link module:core/plugin~PluginInterface.pluginName plugin names}. The second option (names) works only if
 	 * `availablePlugins` were passed to the {@link #constructor}.
 	 * @param {Array.<String|Function>} [removePlugins] Names of plugins or plugin constructors
-	 * which should not be loaded (despite being specified in the `plugins` array).
-	 * @returns {Promise} A promise which gets resolved once all plugins are loaded and available into the
+	 * that should not be loaded (despite being specified in the `plugins` array).
+	 * @returns {Promise} A promise which gets resolved once all plugins are loaded and available in the
 	 * collection.
 	 * @returns {Promise.<Array.<module:core/plugin~PluginInterface>>} returns.loadedPlugins The array of loaded plugins.
 	 */
@@ -102,8 +102,6 @@ export default class PluginCollection {
 		const missingPlugins = getMissingPluginNames( plugins );
 
 		if ( missingPlugins ) {
-			// TODO update this error docs with links to docs because it will be a frequent problem.
-
 			/**
 			 * Some plugins are not available and could not be loaded.
 			 *
@@ -111,9 +109,9 @@ export default class PluginCollection {
 			 * This is usually done by the builder by setting the {@link module:core/editor/editor~Editor.build}
 			 * property.
 			 *
-			 * **If you see this warning when using one of the {@glink builds/index CKEditor 5 Builds}** it means
-			 * that you try to enable a plugin which was not included into that build. This may a be due to a typo
-			 * in the plugin name or simply because that plugin is not part of this build. In the latter scenario,
+			 * **If you see this warning when using one of the {@glink builds/index CKEditor 5 Builds}**, it means
+			 * that you try to enable a plugin which was not included in that build. This may be due to a typo
+			 * in the plugin name or simply because that plugin is not a part of this build. In the latter scenario,
 			 * read more about {@glink builds/guides/development/custom-builds custom builds}.
 			 *
 			 * **If you see this warning when using one of the editor creators directly** (not a build), then it means
@@ -151,11 +149,11 @@ export default class PluginCollection {
 					/**
 					 * It was not possible to load the plugin.
 					 *
-					 * This is a generic error logged to the console when a JavaSript error is thrown during one of
-					 * the plugins initialization.
+					 * This is a generic error logged to the console when a JavaSript error is thrown during the initialization
+					 * of one of the plugins.
 					 *
-					 * If you correctly handled a promise returned by the editor's `create()` method (like shown below)
-					 * you will find the original error logged on the console too:
+					 * If you correctly handled the promise returned by the editor's `create()` method (like shown below)
+					 * you will find the original error logged to the console, too:
 					 *
 					 *		ClassicEditor.create( document.getElementById( 'editor' ) )
 					 *			.then( editor => {
@@ -270,7 +268,7 @@ export default class PluginCollection {
 			/**
 			 * Two plugins with the same {@link module:core/plugin~PluginInterface.pluginName} were loaded.
 			 * This may lead to runtime conflicts between these plugins. This usually means that incorrect
-			 * params were passed to {@link module:core/editor/editor~Editor.create}.
+			 * parameters were passed to {@link module:core/editor/editor~Editor.create}.
 			 *
 			 * @error plugincollection-plugin-name-conflict
 			 * @param {String} pluginName The duplicated plugin name.