Преглед изворни кода

Docs: Table API docs improvements, part 1. [skip ci]

Anna Tomanek пре 6 година
родитељ
комит
6f2e3639fe

+ 3 - 3
packages/ckeditor5-table/src/table.js

@@ -20,7 +20,7 @@ import '../theme/table.css';
  *
  * For a detailed overview, check the {@glink features/table Table feature documentation}.
  *
- * This is a "glue" plugin which loads the {@link module:table/tableediting~TableEditing table editing feature}
+ * This is a "glue" plugin that loads the {@link module:table/tableediting~TableEditing table editing feature}
  * and {@link module:table/tableui~TableUI table UI feature}.
  *
  * @extends module:core/plugin~Plugin
@@ -42,7 +42,7 @@ export default class Table extends Plugin {
 }
 
 /**
- * The configuration of the table features. Used by the table features in the `@ckeditor/ckeditor5-table` package.
+ * The configuration of the table feature. Used by the table feature in the `@ckeditor/ckeditor5-table` package.
  *
  *		ClassicEditor
  *			.create( editorElement, {
@@ -65,7 +65,7 @@ export default class Table extends Plugin {
  */
 
 /**
- * An array of colors definitions (either strings or objects).
+ * An array of color definitions (either strings or objects).
  *
  *		const colors = [
  *			{

+ 4 - 4
packages/ckeditor5-table/src/tablecellproperties.js

@@ -14,7 +14,7 @@ import TableCellPropertiesEditing from './tablecellproperties/tablecellpropertie
 /**
  * The table cell properties feature.
  *
- * This is a "glue" plugin which loads the
+ * This is a "glue" plugin that loads the
  * {@link module:table/tablecellproperties/tablecellpropertiesediting~TableCellPropertiesEditing table cell properties editing feature} and
  * the {@link module:table/tablecellproperties/tablecellpropertiesui~TableCellPropertiesUI table cell properties UI feature}.
  *
@@ -37,10 +37,10 @@ export default class TableCellProperties extends Plugin {
 }
 
 /**
- * A configuration of the table cell properties user interface (balloon). It allows to define:
+ * The configuration of the table cell properties user interface (balloon). It allows to define:
  *
- * * the color palette for the cell border color style field (`tableCellProperties.borderColors`),
- * * the color palette for the cell background style field (`tableCellProperties.backgroundColors`).
+ * * The color palette for the cell border color style field (`tableCellProperties.borderColors`),
+ * * The color palette for the cell background style field (`tableCellProperties.backgroundColors`).
  *
  *		const tableConfig = {
  *			tableCellProperties: {

+ 4 - 4
packages/ckeditor5-table/src/tableediting.js

@@ -112,7 +112,7 @@ export default class TableEditing extends Plugin {
 		conversion.attributeToAttribute( { model: 'colspan', view: 'colspan' } );
 		conversion.attributeToAttribute( { model: 'rowspan', view: 'rowspan' } );
 
-		// Table heading rows and cols conversion.
+		// Table heading rows and columns conversion.
 		conversion.for( 'editingDowncast' ).add( downcastTableHeadingColumnsChange( { asWidget: true } ) );
 		conversion.for( 'dataDowncast' ).add( downcastTableHeadingColumnsChange() );
 		conversion.for( 'editingDowncast' ).add( downcastTableHeadingRowsChange( { asWidget: true } ) );
@@ -143,7 +143,7 @@ export default class TableEditing extends Plugin {
 		injectTableCellRefreshPostFixer( model );
 		injectTableCellParagraphPostFixer( model );
 
-		// Handle tab key navigation.
+		// Handle Tab key navigation.
 		this.editor.keystrokes.set( 'Tab', ( ...args ) => this._handleTabOnSelectedTable( ...args ), { priority: 'low' } );
 		this.editor.keystrokes.set( 'Tab', this._getTabHandler( true ), { priority: 'low' } );
 		this.editor.keystrokes.set( 'Shift+Tab', this._getTabHandler( false ), { priority: 'low' } );
@@ -188,7 +188,7 @@ export default class TableEditing extends Plugin {
 	 * inside table cell.
 	 *
 	 * @private
-	 * @param {Boolean} isForward Whether this handler will move selection to the next cell or previous.
+	 * @param {Boolean} isForward Whether this handler will move the selection to the next or the previous cell.
 	 */
 	_getTabHandler( isForward ) {
 		const editor = this.editor;
@@ -215,7 +215,7 @@ export default class TableEditing extends Plugin {
 			const isFirstCellInRow = currentCellIndex === 0;
 
 			if ( !isForward && isFirstCellInRow && currentRowIndex === 0 ) {
-				// It's the first cell of a table - don't do anything (stay in current position).
+				// It's the first cell of the table - don't do anything (stay in the current position).
 				return;
 			}
 

+ 4 - 4
packages/ckeditor5-table/src/tableproperties.js

@@ -15,7 +15,7 @@ import TablePropertiesUI from './tableproperties/tablepropertiesui';
 /**
  * The table properties feature.
  *
- * This is a "glue" plugin which loads the
+ * This is a "glue" plugin that loads the
  * {@link module:table/tableproperties/tablepropertiesediting~TablePropertiesEditing table editing feature} and
  * the {@link module:table/tableproperties/tablepropertiesui~TablePropertiesUI table properties UI feature}.
  *
@@ -38,10 +38,10 @@ export default class TableProperties extends Plugin {
 }
 
 /**
- * A configuration of the table properties user interface (balloon). It allows to define:
+ * The configuration of the table properties user interface (balloon). It allows to define:
  *
- * * the color palette for the table border color style field (`tableProperties.borderColors`),
- * * the color palette for the table background style field (`tableProperties.backgroundColors`).
+ * * The color palette for the table border color style field (`tableProperties.borderColors`),
+ * * The color palette for the table background style field (`tableProperties.backgroundColors`).
  *
  *		const tableConfig = {
  *			tableProperties: {

+ 6 - 6
packages/ckeditor5-table/src/tabletoolbar.js

@@ -12,9 +12,9 @@ import { getSelectedTableWidget, getTableWidgetAncestor } from './utils';
 import WidgetToolbarRepository from '@ckeditor/ckeditor5-widget/src/widgettoolbarrepository';
 
 /**
- * The table toolbar class. It creates toolbars for the table feature and its content (for now only for a table cell content).
+ * The table toolbar class. It creates toolbars for the table feature and its content (for now only for the table cell content).
  *
- * Table toolbar shows up when a table widget is selected. Its components (e.g. buttons) are created based on the
+ * The table toolbar shows up when a table widget is selected. Its components (e.g. buttons) are created based on the
  * {@link module:table/table~TableConfig#tableToolbar `table.tableToolbar` configuration option}.
  *
  * Table content toolbar shows up when the selection is inside the content of a table. It creates its component based on the
@@ -69,7 +69,7 @@ export default class TableToolbar extends Plugin {
 
 /**
  * Items to be placed in the table content toolbar.
- * The {@link module:table/tabletoolbar~TableToolbar} plugin is required to make this toolbar working.
+ * The {@link module:table/tabletoolbar~TableToolbar} plugin is required to make this toolbar work.
  *
  * Assuming that you use the {@link module:table/tableui~TableUI} feature, the following toolbar items will be available
  * in {@link module:ui/componentfactory~ComponentFactory}:
@@ -87,14 +87,14 @@ export default class TableToolbar extends Plugin {
  * Of course, the same buttons can also be used in the
  * {@link module:core/editor/editorconfig~EditorConfig#toolbar main editor toolbar}.
  *
- * Read more about configuring toolbar in {@link module:core/editor/editorconfig~EditorConfig#toolbar}.
+ * Read more about configuring the toolbar in {@link module:core/editor/editorconfig~EditorConfig#toolbar}.
  *
  * @member {Array.<String>} module:table/table~TableConfig#contentToolbar
  */
 
 /**
  * Items to be placed in the table toolbar.
- * The {@link module:table/tabletoolbar~TableToolbar} plugin is required to make this toolbar working.
+ * The {@link module:table/tabletoolbar~TableToolbar} plugin is required to make this toolbar work.
  *
  * You can thus configure the toolbar like this:
  *
@@ -105,7 +105,7 @@ export default class TableToolbar extends Plugin {
  * Of course, the same buttons can also be used in the
  * {@link module:core/editor/editorconfig~EditorConfig#toolbar main editor toolbar}.
  *
- * Read more about configuring toolbar in {@link module:core/editor/editorconfig~EditorConfig#toolbar}.
+ * Read more about configuring the toolbar in {@link module:core/editor/editorconfig~EditorConfig#toolbar}.
  *
  * @member {Array.<String>} module:table/table~TableConfig#tableToolbar
  */

+ 5 - 5
packages/ckeditor5-table/src/tableui.js

@@ -27,7 +27,7 @@ import tableMergeCellIcon from './../theme/icons/table-merge-cell.svg';
  * * The `'tableRow'` dropdown,
  * * The `'mergeTableCells'` dropdown.
  *
- * The `'tableColumn'`, `'tableRow'`, `'mergeTableCells'` dropdowns work best with {@link module:table/tabletoolbar~TableToolbar}.
+ * The `'tableColumn'`, `'tableRow'` and `'mergeTableCells'` dropdowns work best with {@link module:table/tabletoolbar~TableToolbar}.
  *
  * @extends module:core/plugin~Plugin
  */
@@ -208,7 +208,7 @@ export default class TableUI extends Plugin {
 	}
 
 	/**
-	 * Creates a dropdown view from the set of options.
+	 * Creates a dropdown view from a set of options.
 	 *
 	 * @private
 	 * @param {String} label The dropdown button label.
@@ -255,11 +255,11 @@ export default class TableUI extends Plugin {
 
 // Adds an option to a list view.
 //
-// @param {module:table/tableui~DropdownOption} option Configuration option.
+// @param {module:table/tableui~DropdownOption} option A configuration option.
 // @param {module:core/editor/editor~Editor} editor
-// @param {Array.<module:core/command~Command>} commands List of commands to update.
+// @param {Array.<module:core/command~Command>} commands The list of commands to update.
 // @param {Iterable.<module:ui/dropdown/utils~ListDropdownItemDefinition>} itemDefinitions
-// Collection of dropdown items to update with given option.
+// A collection of dropdown items to update with the given option.
 function addListOption( option, editor, commands, itemDefinitions ) {
 	const model = option.model = new Model( option.model );
 	const { commandName, bindIsOn } = option.model;

+ 16 - 16
packages/ckeditor5-table/src/tableutils.js

@@ -28,7 +28,7 @@ export default class TableUtils extends Plugin {
 	/**
 	 * Returns the table cell location as an object with table row and table column indexes.
 	 *
-	 * For instance in the table below:
+	 * For instance, in the table below:
 	 *
 	 *		    0   1   2   3
 	 *		  +---+---+---+---+
@@ -68,14 +68,14 @@ export default class TableUtils extends Plugin {
 	}
 
 	/**
-	 * Creates an empty table with proper structure. The table needs to be inserted into the model,
-	 * ie. using {@link module:engine/model/model~Model#insertContent} function.
+	 * Creates an empty table with a proper structure. The table needs to be inserted into the model,
+	 * for example, by using the {@link module:engine/model/model~Model#insertContent} function.
 	 *
 	 *		model.change( ( writer ) => {
 	 *			// Create a table of 2 rows and 7 columns:
 	 *			const table = tableUtils.createTable( writer, 2, 7);
 	 *
-	 *			// Insert table to the model at the best position taking current selection:
+	 *			// Insert a table to the model at the best position taking the current selection:
 	 *			model.insertContent( table );
 	 *		}
 	 *
@@ -114,7 +114,7 @@ export default class TableUtils extends Plugin {
 	 *
 	 * @param {module:engine/model/element~Element} table The table model element where the rows will be inserted.
 	 * @param {Object} options
-	 * @param {Number} [options.at=0] Row index at which the rows will be inserted.
+	 * @param {Number} [options.at=0] The row index at which the rows will be inserted.
 	 * @param {Number} [options.rows=1] The number of rows to insert.
 	 */
 	insertRows( table, options = {} ) {
@@ -189,7 +189,7 @@ export default class TableUtils extends Plugin {
 	 *
 	 * @param {module:engine/model/element~Element} table The table model element where the columns will be inserted.
 	 * @param {Object} options
-	 * @param {Number} [options.at=0] Column index at which the columns will be inserted.
+	 * @param {Number} [options.at=0] The column index at which the columns will be inserted.
 	 * @param {Number} [options.columns=1] The number of columns to insert.
 	 */
 	insertColumns( table, options = {} ) {
@@ -259,7 +259,7 @@ export default class TableUtils extends Plugin {
 	 * The cell will be visually split into more cells by updating colspans of other cells in a column
 	 * and inserting cells (columns) after that cell.
 	 *
-	 * In the table below, if cell "a" is split to 3 cells:
+	 * In the table below, if cell "a" is split into 3 cells:
 	 *
 	 *		+---+---+---+
 	 *		| a | b | c |
@@ -286,7 +286,7 @@ export default class TableUtils extends Plugin {
 	 *		| b | c | d |
 	 *		+---+---+---+
 	 *
-	 * Splitting cell "a" with `colspan=3` to 2 cells will create 1 cell with a `colspan=a` and cell "a" that will have `colspan=2`:
+	 * Splitting cell "a" with `colspan=3` into 2 cells will create 1 cell with a `colspan=a` and cell "a" that will have `colspan=2`:
 	 *
 	 *		+---+---+---+
 	 *		| a     |   |
@@ -383,7 +383,7 @@ export default class TableUtils extends Plugin {
 	 * The cell will be visually split into more cells by updating rowspans of other cells in the row and inserting rows with a single cell
 	 * below.
 	 *
-	 * If in the table below cell "b" is split to 3 cells:
+	 * If in the table below cell "b" is split into 3 cells:
 	 *
 	 *		+---+---+---+
 	 *		| a | b | c |
@@ -418,7 +418,7 @@ export default class TableUtils extends Plugin {
 	 *		|   | h | i |
 	 *		+---+---+---+
 	 *
-	 * Splitting cell "a" with `rowspan=4` to 3 cells will create 2 cells with a `rowspan=1` and cell "a" will have `rowspan=2`:
+	 * Splitting cell "a" with `rowspan=4` into 3 cells will create 2 cells with a `rowspan=1` and cell "a" will have `rowspan=2`:
 	 *
 	 *		+---+---+---+
 	 *		| a | b | c |
@@ -556,9 +556,9 @@ export default class TableUtils extends Plugin {
 //
 // @param {module:engine/model/writer~Writer} writer
 // @param {module:engine/model/element~Element} table
-// @param {Number} insertAt Row index of row insertion.
-// @param {Number} rows Number of rows to create.
-// @param {Number} tableCellToInsert Number of cells to insert in each row.
+// @param {Number} insertAt The row index of row insertion.
+// @param {Number} rows The number of rows to create.
+// @param {Number} tableCellToInsert The number of cells to insert in each row.
 function createEmptyRows( writer, table, insertAt, rows, tableCellToInsert, attributes = {} ) {
 	for ( let i = 0; i < rows; i++ ) {
 		const tableRow = writer.createElement( 'tableRow' );
@@ -571,7 +571,7 @@ function createEmptyRows( writer, table, insertAt, rows, tableCellToInsert, attr
 
 // Creates cells at a given position.
 //
-// @param {Number} columns Number of columns to create
+// @param {Number} columns The number of columns to create
 // @param {module:engine/model/writer~Writer} writer
 // @param {module:engine/model/position~Position} insertPosition
 function createCells( cells, writer, insertPosition, attributes = {} ) {
@@ -589,8 +589,8 @@ function createCells( cells, writer, insertPosition, attributes = {} ) {
 //
 // as two cells will have a span of 2 and the remainder will go the first cell so its span will change to 3.
 //
-// @param {Number} span Span value do break.
-// @param {Number} numberOfCells Number of resulting spans.
+// @param {Number} span The span value do break.
+// @param {Number} numberOfCells The number of resulting spans.
 // @returns {{newCellsSpan: Number, updatedSpan: Number}}
 function breakSpanEvenly( span, numberOfCells ) {
 	if ( span < numberOfCells ) {

+ 28 - 28
packages/ckeditor5-table/src/tablewalker.js

@@ -8,7 +8,7 @@
  */
 
 /**
- * Table iterator class. It allows to iterate over table cells. For each cell the iterator yields
+ * The table iterator class. It allows to iterate over table cells. For each cell the iterator yields
  * {@link module:table/tablewalker~TableWalkerValue} with proper table cell attributes.
  */
 export default class TableWalker {
@@ -17,7 +17,7 @@ export default class TableWalker {
 	 *
 	 * The table walker iterates internally by traversing the table from row index = 0 and column index = 0.
 	 * It walks row by row and column by column in order to output values defined in the constructor.
-	 * By default it will output only those locations that are occupied by a cell. To include also spanned rows and columns,
+	 * By default it will output only the locations that are occupied by a cell. To include also spanned rows and columns,
 	 * pass the `includeSpanned` option to the constructor.
 	 *
 	 * The most important values of the iterator are column and row indexes of a cell.
@@ -59,7 +59,7 @@ export default class TableWalker {
 	 *			console.log( 'Cell at ' + value.row + ' x ' + value.column + ' : ' + ( value.isSpanned ? 'is spanned' : 'has data' ) );
 	 *		}
 	 *
-	 * will log in the console for the table from previous example:
+	 * will log in the console for the table from the previous example:
 	 *
 	 *		'Cell at 1 x 0 : is spanned'
 	 *		'Cell at 1 x 1 : is spanned'
@@ -72,8 +72,8 @@ export default class TableWalker {
 	 * @param {module:engine/model/element~Element} table A table over which the walker iterates.
 	 * @param {Object} [options={}] An object with configuration.
 	 * @param {Number} [options.column] A column index for which this iterator will output cells.
-	 * @param {Number} [options.startRow=0] A row index for which this iterator should start.
-	 * @param {Number} [options.endRow] A row index for which this iterator should end.
+	 * @param {Number} [options.startRow=0] A row index from which this iterator should start.
+	 * @param {Number} [options.endRow] A row index at which this iterator should end.
 	 * @param {Boolean} [options.includeSpanned=false] Also return values for spanned cells.
 	 */
 	constructor( table, options = {} ) {
@@ -86,7 +86,7 @@ export default class TableWalker {
 		this.table = table;
 
 		/**
-		 * A row index on which this iterator will start.
+		 * A row index from which this iterator will start.
 		 *
 		 * @readonly
 		 * @member {Number}
@@ -94,7 +94,7 @@ export default class TableWalker {
 		this.startRow = options.startRow || 0;
 
 		/**
-		 * A row index on which this iterator will end.
+		 * A row index at which this iterator will end.
 		 *
 		 * @readonly
 		 * @member {Number}
@@ -237,7 +237,7 @@ export default class TableWalker {
 	 * Marks a row to skip in the next iteration. It will also skip cells from the current row if there are any cells from the current row
 	 * to output.
 	 *
-	 * @param {Number} row Row index to skip.
+	 * @param {Number} row The row index to skip.
 	 */
 	skipRow( row ) {
 		this._skipRows.add( row );
@@ -259,11 +259,11 @@ export default class TableWalker {
 	 *
 	 * @private
 	 * @param {module:engine/model/element~Element} cell The table cell to output.
-	 * @param {Number} column Column index (use the cached value).
-	 * @param {Boolean} isSpanned Whether the value is returned for a spanned cell location or actual cell.
-	 * @param {Number} rowspan Rowspan of the current cell.
-	 * @param {Number} colspan Colspan of the current cell.
-	 * @returns {{done: boolean, value: {cell: *, row: Number, column: *, rowspan: *, colspan: *, cellIndex: Number}}}
+	 * @param {Number} column The column index (use the cached value).
+	 * @param {Boolean} isSpanned Whether the value is returned for a spanned cell location or an actual cell.
+	 * @param {Number} rowspan The rowspan of the current cell.
+	 * @param {Number} colspan The colspan of the current cell.
+	 * @returns {{done: Boolean, value: {cell: *, row: Number, column: *, rowspan: *, colspan: *, cellIndex: Number}}}
 	 */
 	_formatOutValue( cell, column, isSpanned, rowspan = 1, colspan = 1 ) {
 		return {
@@ -312,8 +312,8 @@ export default class TableWalker {
 	 * Checks if the current cell location (row x column) is spanned by another cell.
 	 *
 	 * @private
-	 * @param {Number} row Row index of a cell location to check.
-	 * @param {Number} column Column index of a cell location to check.
+	 * @param {Number} row The row index of a cell location to check.
+	 * @param {Number} column The column index of a cell location to check.
 	 * @returns {Boolean}
 	 */
 	_isSpanned( row, column ) {
@@ -329,11 +329,11 @@ export default class TableWalker {
 	}
 
 	/**
-	 * Returns the cell element that is spanned over `row` x `column` location.
+	 * Returns the cell element that is spanned over the `row` x `column` location.
 	 *
 	 * @private
-	 * @param {Number} row Row index of the cell location.
-	 * @param {Number} column Column index of the cell location.
+	 * @param {Number} row The row index of the cell location.
+	 * @param {Number} column The column index of the cell location.
 	 * @returns {module:engine/model/element~Element}
 	 */
 	_getSpanned( row, column ) {
@@ -344,11 +344,11 @@ export default class TableWalker {
 	 * Updates spanned cells map relative to the current cell location and its span dimensions.
 	 *
 	 * @private
-	 * @param {Number} row Row index of a cell.
-	 * @param {Number} column Column index of a cell.
+	 * @param {Number} row The row index of a cell.
+	 * @param {Number} column The column index of a cell.
 	 * @param {Number} rowspan Cell height.
 	 * @param {Number} colspan Cell width.
-	 * @param {module:engine/model/element~Element} cell Cell that is spanned.
+	 * @param {module:engine/model/element~Element} cell A cell that is spanned.
 	 */
 	_recordSpans( row, column, rowspan, colspan, cell ) {
 		// This will update all cell locations after current column - ie a cell has colspan set.
@@ -368,9 +368,9 @@ export default class TableWalker {
 	 * Marks the cell location as spanned by another cell.
 	 *
 	 * @private
-	 * @param {Number} row Row index of the cell location.
-	 * @param {Number} column Column index of the cell location.
-	 * @param {module:engine/model/element~Element} cell Cell that is spanned.
+	 * @param {Number} row The row index of the cell location.
+	 * @param {Number} column The column index of the cell location.
+	 * @param {module:engine/model/element~Element} cell A cell that is spanned.
 	 */
 	_markSpannedCell( row, column, cell ) {
 		if ( !this._spannedCells.has( row ) ) {
@@ -390,10 +390,10 @@ export default class TableWalker {
  * @property {module:engine/model/element~Element} cell The current table cell.
  * @property {Number} row The row index of a cell.
  * @property {Number} column The column index of a cell. Column index is adjusted to widths and heights of previous cells.
- * @param {Boolean} isSpanned Whether the value is returned for a spanned cell location or actual cell.
- * @property {Number} colspan The `colspan` attribute of a cell. It the model attribute is not present, it is set to `1`. For spanned
+ * @param {Boolean} isSpanned Whether the value is returned for a spanned cell location or an actual cell.
+ * @property {Number} colspan The `colspan` attribute of a cell. If the model attribute is not present, it is set to `1`. For spanned
  * table locations, it is set to `1`.
- * @property {Number} rowspan The `rowspan` attribute of a cell. It the model attribute is not present, it is set to `1`. For spanned
+ * @property {Number} rowspan The `rowspan` attribute of a cell. If the model attribute is not present, it is set to `1`. For spanned
  * table locations, it is set to `1`.
- * @property {Number} cellIndex The index of the current cell in a parent row.
+ * @property {Number} cellIndex The index of the current cell in the parent row.
  */

+ 1 - 1
packages/ckeditor5-table/src/utils.js

@@ -53,7 +53,7 @@ export function getSelectedTableWidget( selection ) {
 }
 
 /**
- * Returns a table widget editing view element if one is among selection's ancestors.
+ * Returns a table widget editing view element if one is among the selection's ancestors.
  *
  * @param {module:engine/view/selection~Selection|module:engine/view/documentselection~DocumentSelection} selection
  * @returns {module:engine/view/element~Element|null}