diff -u b/core/includes/database.inc b/core/includes/database.inc
--- b/core/includes/database.inc
+++ b/core/includes/database.inc
@@ -654,11 +654,9 @@
  *   The name of the index.
  * @param $fields
  *   An array of field names.
- * @param array $spec
- *   A table specification.
  */
-function db_add_index($table, $name, $fields, array $spec) {
-  return Database::getConnection()->schema()->addIndex($table, $name, $fields, $spec);
+function db_add_index($table, $name, $fields) {
+  return Database::getConnection()->schema()->addIndex($table, $name, $fields);
 }
 
 /**
@@ -907,16 +905,22 @@
  *   The name of the index.
  * @param array $fields
  *   An array of field names.
+ * @param array $spec
+ *   The table specification of the table to be altered, as taken from a schema
+ *   definition. See \Drupal\Core\Database\Schema::addIndex() for how to obtain
+ *   this specification.
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container, get
  *   its schema driver, and call addIndex() on it. E.g.
- *   $injected_database->schema()->addIndex($table, $name, $fields);
+ *   $injected_database->schema()->addIndex($table, $name, $fields, $spec);
  *
+ * @see hook_schema()
+ * @see schemaapi
  * @see \Drupal\Core\Database\Schema::addIndex()
  */
 function db_add_index($table, $name, $fields) {
-  return Database::getConnection()->schema()->addIndex($table, $name, $fields);
+  return Database::getConnection()->schema()->addIndex($table, $name, $fields, $spec);
 }
 
 /**
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,13 +414,48 @@
    *     $fields = ['foo', ['bar', 4]];
    *   @endcode
    * @param array $spec
-   *   A table specification, which is used in order to be able to ensure that
-   *   the index length is not too long.
+   *   The table specification for the table to be altered, which 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 
+   *   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:
+   *   @code
+   *   $spec = [
+   *     // Example partial specification for a table:
+   *     'fields' => [
+   *       'example_field' => [
+   *         'description' => 'An example field',
+   *         'type' => 'varchar',
+   *         'length' => 32,
+   *         'not null' => TRUE,
+   *         'default' => '',
+   *       ],
+   *     ],
+   *     'indexes' => [
+   *       'table_example_field' => ['example_field'],
+   *     ],
+   *   ];
+   *   @endcode
+   *   Please note the above is a partial table definition and usually we would
+   *   pass a complete table definition as obtained through hook_schema()
+   *   instead.
+   *
+   * @see schemaapi
+   * @see hook_schema()
    *
    * @throws \Drupal\Core\Database\SchemaObjectDoesNotExistException
    *   If the specified table doesn't exist.
    * @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.
    */
   abstract public function addIndex($table, $name, $fields, array $spec);