8
0
Просмотр исходного кода

Docs: Table feature API docs corrections, part 2. [skip ci]

Anna Tomanek 7 лет назад
Родитель
Сommit
c987e71063

+ 7 - 6
packages/ckeditor5-table/src/commands/insertcolumncommand.js

@@ -18,18 +18,18 @@ import TableUtils from '../tableutils';
  */
 export default class InsertColumnCommand extends Command {
 	/**
-	 * Creates a new `InsertRowCommand` instance.
+	 * Creates a new `InsertColumnCommand` instance.
 	 *
-	 * @param {module:core/editor/editor~Editor} editor Editor on which this command will be used.
+	 * @param {module:core/editor/editor~Editor} editor An editor on which this command will be used.
 	 * @param {Object} options
-	 * @param {String} [options.order="after"] The order of insertion relative to a column in which caret is located.
-	 * Possible values: "after" and "before".
+	 * @param {String} [options.order="after"] The order of insertion relative to the column in which the caret is located.
+	 * Possible values: `"after"` and `"before"`.
 	 */
 	constructor( editor, options = {} ) {
 		super( editor );
 
 		/**
-		 * The order of insertion relative to a column in which caret is located.
+		 * The order of insertion relative to the column in which the caret is located.
 		 *
 		 * @readonly
 		 * @member {String} module:table/commands/insertcolumncommand~InsertColumnCommand#order
@@ -51,7 +51,8 @@ export default class InsertColumnCommand extends Command {
 	/**
 	 * Executes the command.
 	 *
-	 * Depending on command's {@link #order} value it inserts a column `'before'` or `'after'` the column in which selection is set.
+	 * Depending on the command's {@link #order} value, it inserts a column `'before'` or `'after'` the column in which the selection is
+	 * set.
 	 *
 	 * @fires execute
 	 */

+ 5 - 5
packages/ckeditor5-table/src/commands/insertrowcommand.js

@@ -20,16 +20,16 @@ export default class InsertRowCommand extends Command {
 	/**
 	 * Creates a new `InsertRowCommand` instance.
 	 *
-	 * @param {module:core/editor/editor~Editor} editor Editor on which this command will be used.
+	 * @param {module:core/editor/editor~Editor} editor The editor on which this command will be used.
 	 * @param {Object} options
-	 * @param {String} [options.order="below"] The order of insertion relative to a row in which caret is located.
-	 * Possible values: "above" and "below".
+	 * @param {String} [options.order="below"] The order of insertion relative to the row in which the caret is located.
+	 * Possible values: `"above"` and `"below"`.
 	 */
 	constructor( editor, options = {} ) {
 		super( editor );
 
 		/**
-		 * The order of insertion relative to a row in which caret is located.
+		 * The order of insertion relative to the row in which the caret is located.
 		 *
 		 * @readonly
 		 * @member {String} module:table/commands/insertrowcommand~InsertRowCommand#order
@@ -51,7 +51,7 @@ export default class InsertRowCommand extends Command {
 	/**
 	 * Executes the command.
 	 *
-	 * Depending on command's {@link #order} value it inserts a row `'below'` or `'above'` the row in which selection is set.
+	 * Depending on the command's {@link #order} value, it inserts a row `'below'` or `'above'` the row in which selection is set.
 	 *
 	 * @fires execute
 	 */

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

@@ -33,11 +33,11 @@ export default class InsertTableCommand extends Command {
 	/**
 	 * Executes the command.
 	 *
-	 * Inserts table of given rows and columns into the editor.
+	 * Inserts a table with the given number of rows and columns into the editor.
 	 *
 	 * @param {Object} options
-	 * @param {Number} [options.rows=2] Number of rows to create in inserted table.
-	 * @param {Number} [options.columns=2] Number of columns to create in inserted table.
+	 * @param {Number} [options.rows=2] The number of rows to create in the inserted table.
+	 * @param {Number} [options.columns=2] The number of columns to create in the inserted table.
 	 * @fires execute
 	 */
 	execute( options = {} ) {

+ 8 - 8
packages/ckeditor5-table/src/commands/mergecellcommand.js

@@ -21,16 +21,16 @@ export default class MergeCellCommand extends Command {
 	/**
 	 * Creates a new `MergeCellCommand` instance.
 	 *
-	 * @param {module:core/editor/editor~Editor} editor Editor on which this command will be used.
+	 * @param {module:core/editor/editor~Editor} editor The editor on which this command will be used.
 	 * @param {Object} options
-	 * @param {String} options.direction Indicates which cell merge to currently selected one.
-	 * Possible values are: "left", "right", "up" and "down".
+	 * @param {String} options.direction Indicates which cell to merge with the currently selected one.
+	 * Possible values are: `'left'`, `'right'`, `'up'` and `'down'`.
 	 */
 	constructor( editor, options ) {
 		super( editor );
 
 		/**
-		 * The direction indicates which cell will be merged to currently selected one.
+		 * The direction that indicates which cell will be merged with the currently selected one.
 		 *
 		 * @readonly
 		 * @member {String} #direction
@@ -61,7 +61,7 @@ export default class MergeCellCommand extends Command {
 	/**
 	 * Executes the command.
 	 *
-	 * Depending on command's {@link #direction} value it will merge a cell that is to the `'left'`, `'right'`, `'up'` or `'down'`.
+	 * Depending on the command's {@link #direction} value, it will merge the cell that is to the `'left'`, `'right'`, `'up'` or `'down'`.
 	 *
 	 * @fires execute
 	 */
@@ -93,7 +93,7 @@ export default class MergeCellCommand extends Command {
 	}
 
 	/**
-	 * Returns a cell that is mergeable with current cell depending on command's direction.
+	 * Returns a cell that can be merged with the current cell depending on the command's direction.
 	 *
 	 * @returns {module:engine/model/element|undefined}
 	 * @private
@@ -126,7 +126,7 @@ export default class MergeCellCommand extends Command {
 	}
 }
 
-// Returns horizontally mergeable cell.
+// Returns the cell that can be merged horizontally.
 //
 // @param {module:engine/model/element~Element} tableCell
 // @param {String} direction
@@ -135,7 +135,7 @@ function getHorizontalCell( tableCell, direction ) {
 	return direction == 'right' ? tableCell.nextSibling : tableCell.previousSibling;
 }
 
-// Returns vertically mergeable cell.
+// Returns the cell that can be merged vertically.
 //
 // @param {module:engine/model/element~Element} tableCell
 // @param {String} direction

+ 2 - 2
packages/ckeditor5-table/src/commands/setheadercolumncommand.js

@@ -46,9 +46,9 @@ export default class SetHeaderColumnCommand extends Command {
 	/**
 	 * Executes the command.
 	 *
-	 * When the selection is non-header column, the command will set `headingColumns` table's attribute to cover that column.
+	 * When the selection is in a non-header column, the command will set the `headingColumns` table attribute to cover that column.
 	 *
-	 * When selection is already in a header column then it will set `headingColumns` so the heading section will end before that column.
+	 * When the selection is already in a header column, it will set `headingColumns` so the heading section will end before that column.
 	 *
 	 * @fires execute
 	 */

+ 6 - 6
packages/ckeditor5-table/src/commands/setheaderrowcommand.js

@@ -48,9 +48,9 @@ export default class SetHeaderRowCommand extends Command {
 	/**
 	 * Executes the command.
 	 *
-	 * When the selection is non-header row, the command will set `headingRows` table's attribute to cover that row.
+	 * When the selection is in a non-header row, the command will set the `headingRows` table attribute to cover that row.
 	 *
-	 * When selection is already in a header row then it will set `headingRows` so the heading section will end before that row.
+	 * When the selection is already in a header row, it will set `headingRows` so the heading section will end before that row.
 	 *
 	 * @fires execute
 	 */
@@ -87,7 +87,7 @@ export default class SetHeaderRowCommand extends Command {
 	}
 
 	/**
-	 * Checks if table cell is in heading section.
+	 * Checks if a table cell is in the heading section.
 	 *
 	 * @param {module:engine/model/element~Element} tableCell
 	 * @param {module:engine/model/element~Element} table
@@ -101,9 +101,9 @@ export default class SetHeaderRowCommand extends Command {
 	}
 }
 
-// Returns cells that span beyond new heading section.
+// Returns cells that span beyond the new heading section.
 //
-// @param {module:engine/model/element~Element} table Table to check
+// @param {module:engine/model/element~Element} table The table to check.
 // @param {Number} headingRowsToSet New heading rows attribute.
 // @param {Number} currentHeadingRows Current heading rows attribute.
 // @returns {Array.<module:engine/model/element~Element>}
@@ -125,7 +125,7 @@ function getOverlappingCells( table, headingRowsToSet, currentHeadingRows ) {
 	return cellsToSplit;
 }
 
-// Splits table cell horizontally.
+// Splits the table cell horizontally.
 //
 // @param {module:engine/model/element~Element} tableCell
 // @param {Number} headingRows

+ 2 - 2
packages/ckeditor5-table/src/commands/splitcellcommand.js

@@ -19,7 +19,7 @@ export default class SplitCellCommand extends Command {
 	/**
 	 * Creates a new `SplitCellCommand` instance.
 	 *
-	 * @param {module:core/editor/editor~Editor} editor Editor on which this command will be used.
+	 * @param {module:core/editor/editor~Editor} editor The editor on which this command will be used.
 	 * @param {Object} options
 	 * @param {String} options.direction Indicates whether the command should split cells `'horizontally'` or `'vertically'`.
 	 */
@@ -27,7 +27,7 @@ export default class SplitCellCommand extends Command {
 		super( editor );
 
 		/**
-		 * The direction indicates which cell will be split.
+		 * The direction that indicates which cell will be split.
 		 *
 		 * @readonly
 		 * @member {String} #direction

+ 4 - 4
packages/ckeditor5-table/src/commands/utils.js

@@ -8,7 +8,7 @@
  */
 
 /**
- * Returns parent table.
+ * Returns the parent table.
  *
  * @param {module:engine/model/position~Position} position
  * @returns {module:engine/model/element~Element|module:engine/model/documentfragment~DocumentFragment}
@@ -26,13 +26,13 @@ export function getParentTable( position ) {
 }
 
 /**
- * Common method to update numeric value. If value is default one it will be unset.
+ * A common method to update the numeric value. If a value is the default one, it will be unset.
  *
  * @param {String} key Attribute key.
- * @param {*} value Attribute new value.
+ * @param {*} value The new attribute value.
  * @param {module:engine/model/item~Item} item Model item on which the attribute will be set.
  * @param {module:engine/model/writer~Writer} writer
- * @param {*} defaultValue Default attribute value if value is lower or equal then it will be unset.
+ * @param {*} defaultValue Default attribute value. If a value is lower or equal, it will be unset.
  */
 export function updateNumericAttribute( key, value, item, writer, defaultValue = 1 ) {
 	if ( value > defaultValue ) {

+ 26 - 26
packages/ckeditor5-table/src/converters/downcast.js

@@ -16,10 +16,10 @@ import { toTableWidget } from '../utils';
 /**
  * Model table element to view table element conversion helper.
  *
- * This conversion helper creates whole table element with child elements.
+ * This conversion helper creates the whole table element with child elements.
  *
  * @param {Object} options
- * @param {Boolean} options.asWidget If set to true the downcast conversion will produce widget.
+ * @param {Boolean} options.asWidget If set to `true`, the downcast conversion will produce a widget.
  * @returns {Function} Conversion helper.
  */
 export function downcastInsertTable( options = {} ) {
@@ -78,9 +78,9 @@ export function downcastInsertTable( options = {} ) {
 }
 
 /**
- * Model row element to view <tr> element conversion helper.
+ * Model row element to view `<tr>` element conversion helper.
  *
- * This conversion helper creates whole <tr> element with child elements.
+ * This conversion helper creates the whole `<tr>` element with child elements.
  *
  * @returns {Function} Conversion helper.
  */
@@ -121,10 +121,10 @@ export function downcastInsertRow( options = {} ) {
 }
 
 /**
- * Model tableCEll element to view <td> or <th> element conversion helper.
+ * Model table cell element to view `<td>` or `<th>` element conversion helper.
  *
- * This conversion helper will create proper <th> elements for tableCells that are in heading section (heading row or column)
- * and <td> otherwise.
+ * This conversion helper will create proper `<th>` elements for table cells that are in the heading section (heading row or column)
+ * and `<td>` otherwise.
  *
  * @returns {Function} Conversion helper.
  */
@@ -163,13 +163,13 @@ export function downcastInsertCell( options = {} ) {
 }
 
 /**
- * Conversion helper that acts on headingRows table attribute change.
+ * Conversion helper that acts on heading rows table attribute change.
  *
  * This converter will:
  *
- * * rename <td> to <th> elements or vice versa depending on headings,
- * * create <thead> or <tbody> elements if needed,
- * * remove empty <thead> or <tbody> if needed.
+ * * Rename `<td>` to `<th>` elements or vice versa depending on headings.
+ * * Create `<thead>` or `<tbody>` elements if needed.
+ * * Remove empty `<thead>` or `<tbody>` if needed.
  *
  * @returns {Function} Conversion helper.
  */
@@ -240,9 +240,9 @@ export function downcastTableHeadingRowsChange( options = {} ) {
 }
 
 /**
- * Conversion helper that acts on headingColumns table attribute change.
+ * Conversion helper that acts on heading columns table attribute change.
  *
- * Depending on changed attributes this converter will rename <td> to <th> elements or vice versa depending of cell column index.
+ * Depending on changed attributes this converter will rename `<td` to `<th>` elements or vice versa depending of the cell column index.
  *
  * @returns {Function} Conversion helper.
  */
@@ -278,7 +278,7 @@ export function downcastTableHeadingColumnsChange( options = {} ) {
 }
 
 /**
- * Conversion helper that acts on removed row.
+ * Conversion helper that acts on a removed row.
  *
  * @returns {Function} Conversion helper.
  */
@@ -307,7 +307,7 @@ export function downcastRemoveRow() {
 	}, { priority: 'higher' } );
 }
 
-// Renames table cell in the view to given element name.
+// Renames a table cell in the view to a given element name.
 //
 // @param {module:engine/model/element~Element} tableCell
 // @param {String} desiredCellElementName
@@ -332,7 +332,7 @@ function renameViewTableCell( tableCell, desiredCellElementName, conversionApi,
 	conversionApi.mapper.bindElements( tableCell, renamedCell );
 }
 
-// Renames a table cell element in a view according to it's location in table.
+// Renames a table cell element in the view according to its location in the table.
 //
 // @param {module:table/tablewalker~TableWalkerValue} tableWalkerValue
 // @param {{headingColumns, headingRows}} tableAttributes
@@ -353,7 +353,7 @@ function renameViewTableCellIfRequired( tableWalkerValue, tableAttributes, conve
 	}
 }
 
-// Creates a table cell element in a view.
+// Creates a table cell element in the view.
 //
 // @param {module:table/tablewalker~TableWalkerValue} tableWalkerValue
 // @param {module:engine/view/position~Position} insertPosition
@@ -372,7 +372,7 @@ function createViewTableCellElement( tableWalkerValue, tableAttributes, insertPo
 	conversionApi.writer.insert( insertPosition, cellElement );
 }
 
-// Creates or returns an existing tr element from a view.
+// Creates or returns an existing `<tr>` element from the view.
 //
 // @param {module:engine/view/element~Element} tableRow
 // @param {Number} rowIndex
@@ -399,7 +399,7 @@ function getOrCreateTr( tableRow, rowIndex, tableSection, conversionApi ) {
 	return trElement;
 }
 
-// Returns `th` for heading cells and `td` for other cells for current table walker value.
+// Returns `th` for heading cells and `td` for other cells for the current table walker value.
 //
 // @param {module:table/tablewalker~TableWalkerValue} tableWalkerValue
 // @param {{headingColumns, headingRows}} tableAttributes
@@ -422,7 +422,7 @@ function getCellElementName( tableWalkerValue, tableAttributes ) {
 	return isRowHeading ? 'th' : 'td';
 }
 
-// Returns table section name for current table walker value.
+// Returns the table section name for the current table walker value.
 //
 // @param {Number} row
 // @param {{headingColumns, headingRows}} tableAttributes
@@ -431,12 +431,12 @@ function getSectionName( row, tableAttributes ) {
 	return row < tableAttributes.headingRows ? 'thead' : 'tbody';
 }
 
-// Creates or returns an existing <tbody> or <thead> element witch caching.
+// Creates or returns an existing `<tbody>` or `<thead>` element witch caching.
 //
 // @param {String} sectionName
 // @param {module:engine/view/element~Element} viewTable
 // @param {Object} conversionApi
-// @param {Object} cachedTableSection An object on which store cached elements.
+// @param {Object} cachedTableSection An object that stores cached elements.
 // @returns {module:engine/view/containerelement~ContainerElement}
 function getOrCreateTableSection( sectionName, viewTable, conversionApi ) {
 	const viewTableSection = getExistingTableSectionElement( sectionName, viewTable );
@@ -444,7 +444,7 @@ function getOrCreateTableSection( sectionName, viewTable, conversionApi ) {
 	return viewTableSection ? viewTableSection : createTableSection( sectionName, viewTable, conversionApi );
 }
 
-// Finds an existing <tbody> or <thead> element or returns undefined.
+// Finds an existing `<tbody>` or `<thead>` element or returns undefined.
 //
 // @param {String} sectionName
 // @param {module:engine/view/element~Element} tableElement
@@ -457,7 +457,7 @@ function getExistingTableSectionElement( sectionName, tableElement ) {
 	}
 }
 
-// Creates table section at the end of a table.
+// Creates a table section at the end of the table.
 //
 // @param {String} sectionName
 // @param {module:engine/view/element~Element} tableElement
@@ -471,7 +471,7 @@ function createTableSection( sectionName, tableElement, conversionApi ) {
 	return tableChildElement;
 }
 
-// Removes an existing <tbody> or <thead> element if it is empty.
+// Removes an existing `<tbody>` or `<thead>` element if it is empty.
 //
 // @param {String} sectionName
 // @param {module:engine/view/element~Element} tableElement
@@ -484,7 +484,7 @@ function removeTableSectionIfEmpty( sectionName, tableElement, conversionApi ) {
 	}
 }
 
-// Moves view table rows associated with passed model rows to provided table section element.
+// Moves view table rows associated with passed model rows to the provided table section element.
 //
 // @param {Array.<module:engine/model/element~Element>} rowsToMove
 // @param {module:engine/view/element~Element} viewTableSection

+ 12 - 11
packages/ckeditor5-table/src/converters/upcasttable.js

@@ -13,7 +13,7 @@ import ModelPosition from '@ckeditor/ckeditor5-engine/src/model/position';
 /**
  * View table element to model table element conversion helper.
  *
- * This conversion helper convert table element as well as tableRows.
+ * This conversion helper converts the table element as well as table rows.
  *
  * @returns {Function} Conversion helper.
  */
@@ -85,11 +85,11 @@ export default function upcastTable() {
 	};
 }
 
-// Scans table rows & extracts required metadata from table:
+// Scans table rows and extracts required metadata from the table:
 //
-// headingRows    - number of rows that goes as table header.
+// headingRows    - the number of rows that goes as table header.
 // headingColumns - max number of row headings.
-// rows           - sorted trs as they should go into the model - ie if <thead> is inserted after <tbody> in the view.
+// rows           - sorted `<tr>`s as they should go into the model - ie. if `<thead>` is inserted after `<tbody>` in the view.
 //
 // @param {module:engine/view/element~Element} viewTable
 // @returns {{headingRows, headingColumns, rows}}
@@ -99,9 +99,10 @@ function scanTable( viewTable ) {
 		headingColumns: 0
 	};
 
-	// The <tbody> and <thead> sections in the DOM doesn't have to be in order <thead> -> <tbody> and there might be more then one of them.
-	// As the model doesn't have those sections rows from different sections must be sorted.
-	// Ie below is a valid HTML table:
+	// The `<tbody>` and <thead> sections in the DOM do not have to be in order `<thead>` -> `<tbody>` and there might be more then one of
+	// them.
+	// As the model does not have those sections, rows from different sections must be sorted.
+	// For example, below is a valid HTML table:
 	//
 	//		<table>
 	//			<tbody><tr><td>2</td></tr></tbody>
@@ -109,7 +110,7 @@ function scanTable( viewTable ) {
 	//			<tbody><tr><td>3</td></tr></tbody>
 	//		</table>
 	//
-	// But browsers will render rows in order as : 1 as heading and 2 & 3 as (body).
+	// But browsers will render rows in order as: 1 as heading and 2 and 3 as (body).
 	const headRows = [];
 	const bodyRows = [];
 
@@ -150,12 +151,12 @@ function scanTable( viewTable ) {
 	return tableMeta;
 }
 
-// Scans <tr> and it's children for metadata:
+// Scans `<tr>` and its children for metadata:
 // - For heading row:
-//     - either add this row to heading or body rows.
+//     - either adds this row to heading or body rows.
 //     - updates number of heading rows.
 // - For body rows:
-//     - calculates number of column headings.
+//     - calculates the number of column headings.
 //
 // @param {module:engine/view/element~Element} tr
 // @returns {Number}

+ 6 - 6
packages/ckeditor5-table/src/ui/inserttableview.js

@@ -14,7 +14,7 @@ import './../../theme/inserttable.css';
 /**
  * The table size view.
  *
- * It renders a 10x10 grid to choose inserted table size.
+ * It renders a 10x10 grid to choose the inserted table size.
  *
  * @extends module:ui/view~View
  * @implements module:ui/dropdown/dropdownpanelfocusable~DropdownPanelFocusable
@@ -29,7 +29,7 @@ export default class InsertTableView extends View {
 		const bind = this.bindTemplate;
 
 		/**
-		 * Collection of the table size box items.
+		 * A collection of table size box items.
 		 *
 		 * @readonly
 		 * @member {module:ui/viewcollection~ViewCollection}
@@ -37,7 +37,7 @@ export default class InsertTableView extends View {
 		this.items = this.createCollection();
 
 		/**
-		 * Currently selected number of rows of a new table.
+		 * The currently selected number of rows of the new table.
 		 *
 		 * @observable
 		 * @member {Number} #rows
@@ -45,7 +45,7 @@ export default class InsertTableView extends View {
 		this.set( 'rows', 0 );
 
 		/**
-		 * Currently selected number of columns of a new table.
+		 * The currently selected number of columns of the new table.
 		 *
 		 * @observable
 		 * @member {Number} #columns
@@ -143,7 +143,7 @@ export default class InsertTableView extends View {
 	}
 
 	/**
-	 * Highlights grid boxes depending on rows & columns selected.
+	 * Highlights grid boxes depending on rows and columns selected.
 	 *
 	 * @private
 	 */
@@ -167,7 +167,7 @@ export default class InsertTableView extends View {
 /**
  * A single grid box view element.
  *
- * This class is used to render table size selection grid in {@link module:table/ui/inserttableview~InsertTableView}
+ * This class is used to render the table size selection grid in {@link module:table/ui/inserttableview~InsertTableView}.
  *
  * @private
  */

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

@@ -24,7 +24,7 @@ export function repositionContextualBalloon( editor ) {
 }
 
 /**
- * Returns the positioning options that controls the geometry of the
+ * Returns the positioning options that control the geometry of the
  * {@link module:ui/panel/balloon/contextualballoon~ContextualBalloon contextual balloon} with respect
  * to the selected element in the editor content.
  *