Browse Source

Docs: Code block API docs fixed. [skip ci]

Anna Tomanek 6 years ago
parent
commit
2789dfcac0

+ 9 - 8
packages/ckeditor5-code-block/src/codeblock.js

@@ -14,10 +14,11 @@ import CodeBlockUI from './codeblockui';
 /**
 /**
  * The code block plugin.
  * The code block plugin.
  *
  *
- * For more information about this feature check the {@glink api/code-block package page}.
+ * For more information about this feature check the {@glink api/code-block package page} and the
+ * {@glink features/code-blocks code block feature guide}.
  *
  *
- * This is a "glue" plugin which loads the {@link module:code-block/codeblockediting~CodeBlockEditing code block editing feature}
- * and {@link module:code-block/codeblockui~CodeBlockUI code block UI feature}.
+ * This is a "glue" plugin that loads the {@link module:code-block/codeblockediting~CodeBlockEditing code block editing feature}
+ * and the {@link module:code-block/codeblockui~CodeBlockUI code block UI feature}.
  *
  *
  * @extends module:core/plugin~Plugin
  * @extends module:core/plugin~Plugin
  */
  */
@@ -50,7 +51,7 @@ export default class CodeBlock extends Plugin {
  *
  *
  *		ClassicEditor
  *		ClassicEditor
  *			.create( editorElement, {
  *			.create( editorElement, {
- * 				codeBlock:  ... // Code block feature configuration.
+ * 				codeBlock:  ... // The code block feature configuration.
  *			} )
  *			} )
  *			.then( ... )
  *			.then( ... )
  *			.catch( ... );
  *			.catch( ... );
@@ -70,7 +71,7 @@ export default class CodeBlock extends Plugin {
  *
  *
  * @typedef {Object} module:code-block/codeblock~CodeBlockLanguageDefinition
  * @typedef {Object} module:code-block/codeblock~CodeBlockLanguageDefinition
  * @property {String} language The name of the language that will be stored in the model attribute. Also, when `class`
  * @property {String} language The name of the language that will be stored in the model attribute. Also, when `class`
- * is not specified, it will also be used to create the CSS class associated with the language (prefixed by "language-").
+ * is not specified, it will be used to create the CSS class associated with the language (prefixed by "language-").
  * @property {String} label The human–readable label associated with the language and displayed in the UI.
  * @property {String} label The human–readable label associated with the language and displayed in the UI.
  * @property {String} [class] The CSS class associated with the language. When not specified the `language`
  * @property {String} [class] The CSS class associated with the language. When not specified the `language`
  * property is used to create a class prefixed by "language-".
  * property is used to create a class prefixed by "language-".
@@ -102,13 +103,13 @@ export default class CodeBlock extends Plugin {
  *
  *
  *		<pre><code class="language-javascript">window.alert( 'Hello world!' )</code></pre>
  *		<pre><code class="language-javascript">window.alert( 'Hello world!' )</code></pre>
  *
  *
- * You can customize the CSS class by specifying an optional `class` property in a language definition:
+ * You can customize the CSS class by specifying an optional `class` property in the language definition:
  *
  *
  *		ClassicEditor
  *		ClassicEditor
  *			.create( document.querySelector( '#editor' ), {
  *			.create( document.querySelector( '#editor' ), {
  *				codeBlock: {
  *				codeBlock: {
  *					languages: [
  *					languages: [
- *						// Do not render CSS class for the plain text code blocks.
+ *						// Do not render the CSS class for the plain text code blocks.
  * 						{ language: 'plaintext', label: 'Plain text', class: '' },
  * 						{ language: 'plaintext', label: 'Plain text', class: '' },
  *
  *
  *						// Use the "php-code" class for PHP code blocks.
  *						// Use the "php-code" class for PHP code blocks.
@@ -144,7 +145,7 @@ export default class CodeBlock extends Plugin {
  *		]
  *		]
  *
  *
  * **Note**: The first language defined in the configuration is considered the default one. This means it will be
  * **Note**: The first language defined in the configuration is considered the default one. This means it will be
- * applied to code blocks loaded from data that have no CSS `class` specified (or no matching `class` in the config).
+ * applied to code blocks loaded from the data that have no CSS `class` specified (or no matching `class` in the configuration).
  * It will also be used when creating new code blocks using the main UI button. By default it is "Plain text".
  * It will also be used when creating new code blocks using the main UI button. By default it is "Plain text".
  *
  *
  * @member {Array.<module:code-block/codeblock~CodeBlockLanguageDefinition>} module:code-block/codeblock~CodeBlockConfig#languages
  * @member {Array.<module:code-block/codeblock~CodeBlockLanguageDefinition>} module:code-block/codeblock~CodeBlockConfig#languages

+ 1 - 1
packages/ckeditor5-code-block/src/codeblockcommand.js

@@ -34,7 +34,7 @@ export default class CodeBlockCommand extends Command {
 	}
 	}
 
 
 	/**
 	/**
-	 * Executes the command. When the command {@link #value is on}, all top-most code blocks within
+	 * Executes the command. When the command {@link #value is on}, all topmost code blocks within
 	 * the selection will be removed. If it is off, all selected blocks will be flattened and
 	 * the selection will be removed. If it is off, all selected blocks will be flattened and
 	 * wrapped by a code block.
 	 * wrapped by a code block.
 	 *
 	 *

+ 4 - 4
packages/ckeditor5-code-block/src/converters.js

@@ -13,7 +13,7 @@ import {
 } from './utils';
 } from './utils';
 
 
 /**
 /**
- * A modelview (both editing and data) converter for the `codeBlock` element.
+ * A model-to-view (both editing and data) converter for the `codeBlock` element.
  *
  *
  * Sample input:
  * Sample input:
  *
  *
@@ -30,7 +30,7 @@ import {
  * @param {module:engine/model/model~Model} model
  * @param {module:engine/model/model~Model} model
  * @param {Array.<module:code-block/codeblock~CodeBlockLanguageDefinition>} languageDefs The normalized language
  * @param {Array.<module:code-block/codeblock~CodeBlockLanguageDefinition>} languageDefs The normalized language
  * configuration passed to the feature.
  * configuration passed to the feature.
- * @param {Boolean} [useLabels=false] When `true`, the `<pre>` will get a `data-language` attribute with a
+ * @param {Boolean} [useLabels=false] When `true`, the `<pre>` element will get a `data-language` attribute with a
  * human–readable label of the language. Used only in the editing.
  * human–readable label of the language. Used only in the editing.
  * @returns {Function} Returns a conversion callback.
  * @returns {Function} Returns a conversion callback.
  */
  */
@@ -83,7 +83,7 @@ export function modelToViewCodeBlockInsertion( model, languageDefs, useLabels =
 }
 }
 
 
 /**
 /**
- * A model → data-view converter for the new line (`softBreak`) separator.
+ * A model-to-data view converter for the new line (`softBreak`) separator.
  *
  *
  * Sample input:
  * Sample input:
  *
  *
@@ -115,7 +115,7 @@ export function modelToDataViewSoftBreakInsertion( model ) {
 }
 }
 
 
 /**
 /**
- * A view → model converter for `<pre>` with `<code>` html.
+ * A view-to-model converter for `<pre>` with the `<code>` HTML.
  *
  *
  * Sample input:
  * Sample input:
  *
  *

+ 1 - 1
packages/ckeditor5-code-block/src/outdentcodeblockcommand.js

@@ -24,7 +24,7 @@ export default class OutdentCodeBlockCommand extends Command {
 		super( editor );
 		super( editor );
 
 
 		/**
 		/**
-		 * A sequence of characters or removed from the line when the command is executed.
+		 * A sequence of characters removed from the line when the command is executed.
 		 *
 		 *
 		 * @readonly
 		 * @readonly
 		 * @private
 		 * @private

+ 10 - 10
packages/ckeditor5-code-block/src/utils.js

@@ -12,11 +12,11 @@ import first from '@ckeditor/ckeditor5-utils/src/first';
 /**
 /**
  * Returns code block languages as defined in `config.codeBlock.languages` but processed:
  * Returns code block languages as defined in `config.codeBlock.languages` but processed:
  *
  *
- * * to consider the editor localization, i.e. to display {@link module:code-block/codeblock~CodeBlockLanguageDefinition}
- * in the correct language — there is no way to use {@link module:utils/locale~Locale#t} when the user
+ * * To consider the editor localization, i.e. to display {@link module:code-block/codeblock~CodeBlockLanguageDefinition}
+ * in the correct language. There is no way to use {@link module:utils/locale~Locale#t} when the user
  * configuration is defined because the editor does not exist yet.
  * configuration is defined because the editor does not exist yet.
- * * to make sure each definition has a CSS class associated with it even if not specified
- * in the original config.
+ * * To make sure each definition has a CSS class associated with it even if not specified
+ * in the original configuration.
  *
  *
  * @param {module:core/editor/editor~Editor} editor
  * @param {module:core/editor/editor~Editor} editor
  * @returns {Array.<module:code-block/codeblock~CodeBlockLanguageDefinition>}.
  * @returns {Array.<module:code-block/codeblock~CodeBlockLanguageDefinition>}.
@@ -39,7 +39,7 @@ export function getNormalizedAndLocalizedLanguageDefinitions( editor ) {
 }
 }
 
 
 /**
 /**
- * Returns an object associating certain language definition properties with another. For instance:
+ * Returns an object associating certain language definition properties with others. For instance:
  *
  *
  * For:
  * For:
  *
  *
@@ -106,7 +106,7 @@ export function getLeadingWhiteSpaces( textNode ) {
  *		</DocumentFragment>
  *		</DocumentFragment>
  *
  *
  * @param {module:engine/model/writer~Writer} writer
  * @param {module:engine/model/writer~Writer} writer
- * @param {String} text A raw code text to be converted.
+ * @param {String} text The raw code text to be converted.
  */
  */
 export function rawSnippetTextToModelDocumentFragment( writer, text ) {
 export function rawSnippetTextToModelDocumentFragment( writer, text ) {
 	const fragment = writer.createDocumentFragment();
 	const fragment = writer.createDocumentFragment();
@@ -140,7 +140,7 @@ export function rawSnippetTextToModelDocumentFragment( writer, text ) {
  *		    baz]qux                                   ^bazqux
  *		    baz]qux                                   ^bazqux
  *		</codeBlock>                               </codeBlock>
  *		</codeBlock>                               </codeBlock>
  *
  *
- * it also works across other non–code blocks:
+ * It also works across other non–code blocks:
  *
  *
  *		<codeBlock>                                <codeBlock>
  *		<codeBlock>                                <codeBlock>
  *		    foo[bar                                   ^foobar
  *		    foo[bar                                   ^foobar
@@ -150,8 +150,8 @@ export function rawSnippetTextToModelDocumentFragment( writer, text ) {
  *		    baz]qux                                   ^bazqux
  *		    baz]qux                                   ^bazqux
  *		</codeBlock>                               </codeBlock>
  *		</codeBlock>                               </codeBlock>
  *
  *
- * **Note:** The positions are in the reverse order so they do not get outdated when iterating over them and
- * the writer inserts or removes things.
+ * **Note:** The positions are in reverse order so they do not get outdated when iterating over them and
+ * the writer inserts or removes things at the same time.
  *
  *
  * **Note:** The position is situated after the leading white spaces in the text node.
  * **Note:** The position is situated after the leading white spaces in the text node.
  *
  *
@@ -194,7 +194,7 @@ export function getIndentOutdentPositions( model ) {
 }
 }
 
 
 /**
 /**
- * Checks if any of the blocks within model selection is a code block.
+ * Checks if any of the blocks within the model selection is a code block.
  *
  *
  * @param {module:engine/model/selection~Selection} selection
  * @param {module:engine/model/selection~Selection} selection
  * @returns {Boolean}
  * @returns {Boolean}