Przeglądaj źródła

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

Anna Tomanek 6 lat temu
rodzic
commit
9daf6513a3

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

@@ -169,7 +169,7 @@ export function downcastInsertCell( options = {} ) {
 }
 
 /**
- * Conversion helper that acts on heading rows table attribute change.
+ * Conversion helper that acts on heading row table attribute change.
  *
  * This converter will:
  *
@@ -246,9 +246,9 @@ export function downcastTableHeadingRowsChange( options = {} ) {
 }
 
 /**
- * Conversion helper that acts on heading columns table attribute change.
+ * Conversion helper that acts on heading column table attribute change.
  *
- * Depending on changed attributes this converter will rename `<td` to `<th>` elements or vice versa depending of the cell column index.
+ * Depending on changed attributes this converter will rename `<td` to `<th>` elements or vice versa depending on the cell column index.
  *
  * @returns {Function} Conversion helper.
  */
@@ -317,7 +317,7 @@ export function downcastRemoveRow() {
 
 // Renames an existing table cell in the view to a given element name.
 //
-// **Note** This method will not do anything if a view table cell was not yet converted.
+// **Note** This method will not do anything if a view table cell has not been converted yet.
 //
 // @param {module:engine/model/element~Element} tableCell
 // @param {String} desiredCellElementName
@@ -414,7 +414,7 @@ function createViewTableCellElement( tableWalkerValue, tableAttributes, insertPo
 	}
 }
 
-// Creates `<tr>` view element.
+// Creates a `<tr>` view element.
 //
 // @param {module:engine/view/element~Element} tableRow
 // @param {Number} rowIndex
@@ -469,7 +469,7 @@ 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 with caching.
 //
 // @param {String} sectionName
 // @param {module:engine/view/element~Element} viewTable
@@ -526,7 +526,7 @@ function removeTableSectionIfEmpty( sectionName, tableElement, conversionApi ) {
 
 // Moves view table rows associated with passed model rows to the provided table section element.
 //
-// **Note** This method will skip not converted table rows.
+// **Note**: This method will skip not converted table rows.
 //
 // @param {Array.<module:engine/model/element~Element>} rowsToMove
 // @param {module:engine/view/element~Element} viewTableSection
@@ -546,7 +546,7 @@ function moveViewRowsToTableSection( rowsToMove, viewTableSection, conversionApi
 	}
 }
 
-// Properly finds '<table>' element inside `<figure>` widget.
+// Finds a '<table>' element inside the `<figure>` widget.
 //
 // @param {module:engine/view/element~Element} viewFigure
 function getViewTable( viewFigure ) {
@@ -557,7 +557,7 @@ function getViewTable( viewFigure ) {
 	}
 }
 
-// Checks if element has any attribute set.
+// Checks if an element has any attributes set.
 //
 // @param {module:engine/model/element~Element element
 // @returns {Boolean}

+ 7 - 7
packages/ckeditor5-table/src/converters/table-cell-paragraph-post-fixer.js

@@ -8,9 +8,9 @@
  */
 
 /**
- * Injects a table cell post-fixer into the model which inserts `paragraph` element into empty table cells.
+ * Injects a table cell post-fixer into the model which inserts a `paragraph` element into empty table cells.
  *
- * A table cell must contain at least one block element as a child. An empty table cell will have empty `paragraph` as a child.
+ * A table cell must contain at least one block element as a child. An empty table cell will have an empty `paragraph` as a child.
  *
  *		<table>
  *			<tableRow>
@@ -91,8 +91,8 @@ function fixTableRow( tableRow, writer ) {
 }
 
 // Fixes all table cell content by:
-// - adding paragraph to a table cell without any child.
-// - wrapping direct $text in <paragraph>.
+// - Adding a paragraph to a table cell without any child.
+// - Wrapping direct $text in a `<paragraph>`.
 //
 // @param {module:engine/model/element~Element} table
 // @param {module:engine/model/writer~Writer} writer
@@ -117,9 +117,9 @@ function fixTableCellContent( tableCell, writer ) {
 	return !!textNodes.length;
 }
 
-// Check if differ change should fix table cell. This happens on:
-// - removing content from table cell (ie tableCell can be left empty).
-// - adding text node directly into a table cell.
+// Checks if a differ change should fix the table cell. This happens on:
+// - Removing content from the table cell (i.e. `tableCell` can be left empty).
+// - Adding a text node directly into a table cell.
 //
 // @param {Object} differ change entry
 // @returns {Boolean}

+ 8 - 8
packages/ckeditor5-table/src/converters/table-cell-refresh-post-fixer.js

@@ -11,10 +11,10 @@
  * Injects a table cell post-fixer into the model which marks the table cell in the differ to have it re-rendered.
  *
  * Model `paragraph` inside a table cell can be rendered as `<span>` or `<p>`. It is rendered as `<span>` if this is the only block
- * element in that table cell and it doesn't have any attributes. It is rendered as `<p>` otherwise.
+ * element in that table cell and it does not have any attributes. It is rendered as `<p>` otherwise.
  *
- * When table cell content changes, for example a second `paragraph` element is added we need to ensure that the first `paragraph` is
- * re-rendered so it changes to `<p>` from `<span>`. The easiest way to do it is to re-render whole table cell.
+ * When table cell content changes, for example a second `paragraph` element is added, we need to ensure that the first `paragraph` is
+ * re-rendered so it changes from `<span>` to `<p>`. The easiest way to do it is to re-render the entire table cell.
  *
  * @param {module:engine/model/model~Model} model
  */
@@ -49,16 +49,16 @@ function tableCellRefreshPostFixer( model ) {
 
 // Checks if the model table cell requires refreshing to be re-rendered to a proper state in the view.
 //
-// This methods detects changes that will require renaming <span> to <p> (or vice versa) in the view.
+// This method detects changes that will require renaming `<span>` to `<p>` (or vice versa) in the view.
 //
 // This method is a simple heuristic that checks only a single change and will sometimes give a false positive result when multiple changes
 // will result in a state that does not require renaming in the view (but will be seen as requiring a refresh).
 //
-// For instance: a `<span>` should be renamed to `<p>` when adding an attribute to a `<paragraph>`.
-// But adding one attribute and removing another one will result in a false positive: the check for added attribute will see one attribute
-// on a paragraph and will falsy qualify such change as adding an attribute to a paragraph without any attribute.
+// For instance: A `<span>` should be renamed to `<p>` when adding an attribute to a `<paragraph>`.
+// But adding one attribute and removing another one will result in a false positive: the check for an added attribute will see one
+// attribute on a paragraph and will falsely qualify such change as adding an attribute to a paragraph without any attribute.
 //
-// @param {module:engine/model/element~Element} tableCell Table cell to check.
+// @param {module:engine/model/element~Element} tableCell The table cell to check.
 // @param {String} type Type of change.
 function checkRefresh( tableCell, type ) {
 	const hasInnerParagraph = Array.from( tableCell.getChildren() ).some( child => child.is( 'paragraph' ) );

+ 39 - 39
packages/ckeditor5-table/src/converters/table-layout-post-fixer.js

@@ -19,19 +19,19 @@ import TableWalker from './../tablewalker';
  * The correct structure means that:
  *
  * * All table rows have the same size.
- * * None of a table cells that extend vertically beyond their section (either header or body).
- * * A table cell has always at least one element as child.
+ * * None of the table cells extend vertically beyond their section (either header or body).
+ * * A table cell has always at least one element as a child.
  *
  * If the table structure is not correct, the post-fixer will automatically correct it in two steps:
  *
- * 1. It will clip table cells that extends beyond it section.
- * 2. It will add empty table cells to those rows which are narrower then the widest table row.
+ * 1. It will clip table cells that extend beyond their section.
+ * 2. It will add empty table cells to the rows that are narrower than the widest table row.
  *
  * ## Clipping overlapping table cells
  *
- * Such situation may occur when pasting a table (or part of a table) to the editor from external sources.
+ * Such situation may occur when pasting a table (or a part of a table) to the editor from external sources.
  *
- * For example, see the following table which has the cell (FOO) with the rowspan attribute (2):
+ * For example, see the following table which has a cell (FOO) with the rowspan attribute (2):
  *
  *		<table headingRows="1">
  *			<tableRow>
@@ -44,7 +44,7 @@ import TableWalker from './../tablewalker';
  *			</tableRow>
  *		</table>
  *
- * will be rendered in the view as:
+ * It will be rendered in the view as:
  *
  *		<table>
  *			<thead>
@@ -61,22 +61,22 @@ import TableWalker from './../tablewalker';
  *			</tbody>
  *		</table>
  *
- * In the above example the table will be rendered as a table with two rows - one in the header and second one in the body.
- * The table cell (FOO) cannot span over multiple rows as it would expand from the header to the body section.
- * The `rowspan` attribute must be changed to (1). The value (1) is a default value of the `rowspan` attribute
+ * In the above example the table will be rendered as a table with two rows: one in the header and second one in the body.
+ * The table cell (FOO) cannot span over multiple rows as it would extend from the header to the body section.
+ * The `rowspan` attribute must be changed to (1). The value (1) is the default value of the `rowspan` attribute
  * so the `rowspan` attribute will be removed from the model.
  *
- * The table cell with BAZ contents will be in the first column of the table.
+ * The table cell with BAZ in the content will be in the first column of the table.
  *
  * ## Adding missing table cells
  *
- * The table post-fixer will insert empty table cells to equalize table rows sizes (number of columns).
- * The size of a table row is calculated by counting column spans of table cells - both horizontal (from the same row) and
- * vertical (from rows above).
+ * The table post-fixer will insert empty table cells to equalize table row sizes (the number of columns).
+ * The size of a table row is calculated by counting column spans of table cells, both horizontal (from the same row) and
+ * vertical (from the rows above).
  *
- * In the above example, the table row in the body section of the table is narrower then the row from the header - it has two cells
- * with the default colspan (1). The header row has one cell with colspan (1) and second with colspan (2).
- * The table cell (FOO) does not expand beyond the head section (and as such will be fixed in the first step of this post-fixer).
+ * In the above example, the table row in the body section of the table is narrower then the row from the header: it has two cells
+ * with the default colspan (1). The header row has one cell with colspan (1) and the second with colspan (2).
+ * The table cell (FOO) does not extend beyond the head section (and as such will be fixed in the first step of this post-fixer).
  * The post-fixer will add a missing table cell to the row in the body section of the table.
  *
  * The table from the above example will be fixed and rendered to the view as below:
@@ -96,15 +96,15 @@ import TableWalker from './../tablewalker';
  *			</tbody>
  *		</table>
  *
- * ## Collaboration & Undo - Expectations vs post-fixer results
+ * ## Collaboration and undo - Expectations vs post-fixer results
  *
- * The table post-fixer only ensures proper structure without deeper analysis of the nature of a change. As such, it might lead
- * to a structure which was not intended by the user changes. In particular, it will also fix undo steps (in conjunction with collaboration)
- * in which editor content might not return to the original state.
+ * The table post-fixer only ensures proper structure without a deeper analysis of the nature of the change. As such, it might lead
+ * to a structure which was not intended by the user. In particular, it will also fix undo steps (in conjunction with collaboration)
+ * in which the editor content might not return to the original state.
  *
- * This will usually happen when one or more users changes size of the table.
+ * This will usually happen when one or more users change the size of the table.
  *
- * As en example see a table below:
+ * As an example see the table below:
  *
  *		<table>
  *			<tbody>
@@ -119,11 +119,11 @@ import TableWalker from './../tablewalker';
  *			</tbody>
  *		</table>
  *
- * and user actions:
+ * and the user actions:
  *
- * 1. Both user have table with two rows and two columns.
- * 2. User A adds a column at the end of the table - this will insert empty table cells to two rows.
- * 3. User B adds a row at the end of the table- this will insert a row with two empty table cells.
+ * 1. Both users have a table with two rows and two columns.
+ * 2. User A adds a column at the end of the table. This will insert empty table cells to two rows.
+ * 3. User B adds a row at the end of the table. This will insert a row with two empty table cells.
  * 4. Both users will have a table as below:
  *
  *
@@ -146,7 +146,7 @@ import TableWalker from './../tablewalker';
  *			</tbody>
  *		</table>
  *
- * The last row is shorter then others so table post-fixer will add empty row to tha last row:
+ * The last row is shorter then others so the table post-fixer will add an empty row to the last row:
  *
  *		<table>
  *			<tbody>
@@ -163,14 +163,14 @@ import TableWalker from './../tablewalker';
  *				<tr>
  *					<td>(empty, inserted by B)</td>
  *					<td>(empty, inserted by B)</td>
- *					<td>(empty, inserted by a post-fixer)</td>
+ *					<td>(empty, inserted by the post-fixer)</td>
  *				</tr>
  *			</tbody>
  *		</table>
  *
- * Unfortunately undo doesn't know the nature of changes and depending which user will apply post-fixer changes undoing them might lead to
- * broken table. If User B will undo inserting column to a table the undo engine will undo only operations of
- * inserting empty cells to rows from initial table state (row 1 & 2) but the cell in post-fixed row will remain:
+ * Unfortunately undo does not know the nature of the changes and depending on which user applies the post-fixer changes, undoing them
+ * might lead to a broken table. If User B undoes inserting the column to the table, the undo engine will undo only the operations of
+ * inserting empty cells to rows from the initial table state (row 1 and 2) but the cell in the post-fixed row will remain:
  *
  *		<table>
  *			<tbody>
@@ -190,7 +190,7 @@ import TableWalker from './../tablewalker';
  *			</tbody>
  *		</table>
  *
- * After undo the table post-fixer will detect that two rows are shorter then other and will fix table to:
+ * After undo, the table post-fixer will detect that two rows are shorter than others and will fix the table to:
  *
  *		<table>
  *			<tbody>
@@ -260,11 +260,11 @@ function tableLayoutPostFixer( writer, model ) {
 	return wasFixed;
 }
 
-// Fixes the invalid value of the rowspan attribute because a table cell cannot vertically extend beyond the table section it belongs to.
+// Fixes the invalid value of the `rowspan` attribute because a table cell cannot vertically extend beyond the table section it belongs to.
 //
 // @param {module:engine/model/element~Element} table
 // @param {module:engine/model/writer~Writer} writer
-// @returns {Boolean} Returns true if table was fixed.
+// @returns {Boolean} Returns `true` if the table was fixed.
 function fixTableCellsRowspan( table, writer ) {
 	let wasFixed = false;
 
@@ -285,7 +285,7 @@ function fixTableCellsRowspan( table, writer ) {
 //
 // @param {module:engine/model/element~Element} table
 // @param {module:engine/model/writer~Writer} writer
-// @returns {Boolean} Returns true if table was fixed.
+// @returns {Boolean} Returns `true` if the table was fixed.
 function fixTableRowsSizes( table, writer ) {
 	let wasFixed = false;
 
@@ -313,8 +313,8 @@ function fixTableRowsSizes( table, writer ) {
 	return wasFixed;
 }
 
-// Searches for the table cells that extends beyond the table section to which they belong to. It will return an array of objects
-// that holds table cells to be trimmed and correct value of a rowspan attribute to set.
+// Searches for table cells that extend beyond the table section to which they belong to. It will return an array of objects
+// that stores table cells to be trimmed and the correct value of the `rowspan` attribute to set.
 //
 // @param {module:engine/model/element~Element} table
 // @returns {Array.<{{cell, rowspan}}>}
@@ -364,7 +364,7 @@ function getRowsLengths( table ) {
 	return lengths;
 }
 
-// Checks if the differ entry for an attribute change is one of table's attributes.
+// Checks if the differ entry for an attribute change is one of the table's attributes.
 //
 // @param entry
 // @returns {Boolean}

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

@@ -8,7 +8,7 @@
  */
 
 /**
- * Conversion helper for upcasting attribute using normalized styles.
+ * Conversion helper for upcasting attributes using normalized styles.
  *
  * @param {module:engine/conversion/conversion~Conversion} conversion
  * @param {String} modelElement
@@ -31,7 +31,7 @@ export function upcastStyleToAttribute( conversion, modelElement, modelAttribute
 }
 
 /**
- * Conversion helper for upcasting border styles for view element.
+ * Conversion helper for upcasting border styles for view elements.
  *
  * @param {module:engine/conversion/conversion~Conversion} conversion
  * @param {String} viewElementName
@@ -71,7 +71,7 @@ export function upcastBorderStyles( conversion, viewElementName ) {
 }
 
 /**
- * Conversion helper for downcasting attribute to a style.
+ * Conversion helper for downcasting an attribute to a style.
  *
  * @param {module:engine/conversion/conversion~Conversion} conversion
  * @param {String} modelElement
@@ -94,7 +94,7 @@ export function downcastAttributeToStyle( conversion, modelElement, modelAttribu
 }
 
 /**
- * Conversion helper for downcasting attributes from model's table to a view table (not to figure).
+ * Conversion helper for downcasting attributes from the model table to a view table (not to `<figure>`).
  *
  * @param {module:engine/conversion/conversion~Conversion} conversion
  * @param {String} modelAttribute

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

@@ -140,9 +140,9 @@ export function upcastTableCell( elementName ) {
 
 // Scans table rows and extracts required metadata from the table:
 //
-// headingRows    - the number of rows that goes as table header.
-// headingColumns - max number of row headings.
-// rows           - sorted `<tr>`s as they should go into the model - ie. if `<thead>` is inserted after `<tbody>` in the view.
+// headingRows    - The number of rows that go as table headers.
+// headingColumns - The maximum number of row headings.
+// rows           - Sorted `<tr>` elements 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}}
@@ -152,9 +152,9 @@ function scanTable( viewTable ) {
 		headingColumns: 0
 	};
 
-	// 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.
+	// The `<tbody>` and `<thead>` sections in the DOM do not have to be in order `<thead>` -> `<tbody>` and there might be more than one
+	// of them.
+	// As the model does not have these sections, rows from different sections must be sorted.
 	// For example, below is a valid HTML table:
 	//
 	//		<table>
@@ -163,7 +163,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 and 3 as (body).
+	// But browsers will render rows in order as: 1 as heading and 2 and 3 as the body.
 	const headRows = [];
 	const bodyRows = [];
 
@@ -208,12 +208,12 @@ function scanTable( viewTable ) {
 	return tableMeta;
 }
 
-// Scans `<tr>` and its children for metadata:
+// Scans a `<tr>` element and its children for metadata:
 // - For heading row:
-//     - either adds this row to heading or body rows.
-//     - updates number of heading rows.
+//     - Adds this row to either the heading or the body rows.
+//     - Updates the number of heading rows.
 // - For body rows:
-//     - calculates the number of column headings.
+//     - Calculates the number of column headings.
 //
 // @param {module:engine/view/element~Element} tr
 // @returns {Number}