diff -u b/core/lib/Drupal/Core/Database/Schema.php b/core/lib/Drupal/Core/Database/Schema.php
--- b/core/lib/Drupal/Core/Database/Schema.php
+++ b/core/lib/Drupal/Core/Database/Schema.php
@@ -414,18 +414,18 @@
    *     $fields = ['foo', ['bar', 4]];
    *   @endcode
    * @param array $spec
-   *   The table specification for the table to be altered, which is used in
+   *   The table specification for the table to be altered. This is used in
    *   order to be able to ensure that the index length is not too long.
    *   This schema definition can usually be obtained through hook_schema(), or
    *   in case the table was created by the Entity API, through the schema
-   *   handler listed in the entity class definition (see
-   *   SqlContentEntityStorageSchema::getDedicatedTableSchema() and 
+   *   handler listed in the entity class definition. For reference, see
+   *   SqlContentEntityStorageSchema::getDedicatedTableSchema() and
    *   SqlContentEntityStorageSchema::getSharedTableFieldSchema().
    *
-   *   To prevent human error, it is recommended to pass in the complete table
-   *   specification. However, in the edge case of the complete table specification
-   *   not being available, we can pass in a partial definition containing only
-   *   the fields that apply to the index:
+   *   In order to prevent human error, it is recommended to pass in the
+   *   complete table specification. However, in the edge case of the complete
+   *   table specification not being available, we can pass in a partial table
+   *   definition containing only the fields that apply to the index:
    *   @code
    *   $spec = [
    *     // Example partial specification for a table:
@@ -443,8 +443,8 @@
    *     ],
    *   ];
    *   @endcode
-   *   Please note the above is a partial table definition and usually we would
-   *   pass a complete table definition as obtained through hook_schema()
+   *   Please note that the above is a partial table definition and that we would
+   *   usually pass a complete table definition as obtained through hook_schema()
    *   instead.
    *
    * @see schemaapi
@@ -455,7 +455,7 @@
    * @throws \Drupal\Core\Database\SchemaObjectExistsException
    *   If the specified table already has an index by that name.
    *
-   * @todo remove the $spec argument when we add schema introspection.
+   * @todo remove the $spec argument whenever schema introspection is added.
    */
   abstract public function addIndex($table, $name, $fields, array $spec);