diff --git a/core/lib/Drupal/Core/Database/Connection.php b/core/lib/Drupal/Core/Database/Connection.php
index 7c4240202da68e6c74f39042d1c3655e3273caf9..33d033744c10b5156fa81b769e6997d00cd6b718 100644
--- a/core/lib/Drupal/Core/Database/Connection.php
+++ b/core/lib/Drupal/Core/Database/Connection.php
@@ -24,7 +24,7 @@ abstract class Connection {
    *
    * We need this information for later auditing and logging.
    *
-   * @var string
+   * @var string|null
    */
   protected $target = NULL;
 
@@ -35,14 +35,14 @@ abstract class Connection {
    * connection can be a single server or a cluster of primary and replicas
    * (use target to pick between primary and replica).
    *
-   * @var string
+   * @var string|null
    */
   protected $key = NULL;
 
   /**
    * The current database logging object for this connection.
    *
-   * @var Log
+   * @var \Drupal\Core\Database\Log|null
    */
   protected $logger = NULL;
 
@@ -111,7 +111,9 @@ abstract class Connection {
   /**
    * The schema object for this connection.
    *
-   * @var object
+   * Set to NULL when the schema is destroyed.
+   *
+   * @var \Drupal\Core\Database\Schema|null
    */
   protected $schema = NULL;
 
@@ -138,6 +140,14 @@ abstract class Connection {
 
   /**
    * Constructs a Connection object.
+   *
+   * @param \PDO $connection
+   *   An object of the PDO class representing a database connection.
+   * @param array $connection_options
+   *   An array of options for the connection. May include the following:
+   *   - prefix
+   *   - namespace
+   *   - Other driver-specific options.
    */
   public function __construct(\PDO $connection, array $connection_options) {
     // Initialize and prepare the connection prefix.
@@ -221,7 +231,7 @@ public function destroy() {
    *   that behavior and simply return NULL on failure, set this option to
    *   FALSE.
    *
-   * @return
+   * @return array
    *   An array of default query options.
    */
   protected function defaultOptions() {
@@ -241,7 +251,7 @@ protected function defaultOptions() {
    * is for requesting the connection information of this specific
    * open connection object.
    *
-   * @return
+   * @return array
    *   An array of the connection information. The exact list of
    *   properties is driver-dependent.
    */
@@ -252,9 +262,9 @@ public function getConnectionOptions() {
   /**
    * Set the list of prefixes used by this database connection.
    *
-   * @param $prefix
-   *   The prefixes, in any of the multiple forms documented in
-   *   default.settings.php.
+   * @param array|string $prefix
+   *   Either a single prefix, or an array of prefixes, in any of the multiple
+   *   forms documented in default.settings.php.
    */
   protected function setPrefix($prefix) {
     if (is_array($prefix)) {
@@ -289,10 +299,10 @@ protected function setPrefix($prefix) {
    * tables, allowing Drupal to coexist with other systems in the same database
    * and/or schema if necessary.
    *
-   * @param $sql
+   * @param string $sql
    *   A string containing a partial or entire SQL query.
    *
-   * @return
+   * @return string
    *   The properly-prefixed string.
    */
   public function prefixTables($sql) {
@@ -304,6 +314,9 @@ public function prefixTables($sql) {
    *
    * This function is for when you want to know the prefix of a table. This
    * is not used in prefixTables due to performance reasons.
+   *
+   * @param string $table
+   *   (optional) The table to find the prefix for.
    */
   public function tablePrefix($table = 'default') {
     if (isset($this->prefixes[$table])) {
@@ -355,9 +368,8 @@ public function prepareQuery($query) {
    * signature. We therefore also ensure that this function is only ever
    * called once.
    *
-   * @param $target
-   *   The target this connection is for. Set to NULL (default) to disable
-   *   logging entirely.
+   * @param string $target
+   *   (optional) The target this connection is for.
    */
   public function setTarget($target = NULL) {
     if (!isset($this->target)) {
@@ -368,8 +380,8 @@ public function setTarget($target = NULL) {
   /**
    * Returns the target this connection is associated with.
    *
-   * @return
-   *   The target string of this connection.
+   * @return string|null
+   *   The target string of this connection, or NULL if no target is set.
    */
   public function getTarget() {
     return $this->target;
@@ -378,7 +390,7 @@ public function getTarget() {
   /**
    * Tells this connection object what its key is.
    *
-   * @param $target
+   * @param string $key
    *   The key this connection is for.
    */
   public function setKey($key) {
@@ -390,8 +402,8 @@ public function setKey($key) {
   /**
    * Returns the key this connection is associated with.
    *
-   * @return
-   *   The key of this connection.
+   * @return string|null
+   *   The key of this connection, or NULL if no key is set.
    */
   public function getKey() {
     return $this->key;
@@ -400,7 +412,7 @@ public function getKey() {
   /**
    * Associates a logging object with this connection.
    *
-   * @param $logger
+   * @param \Drupal\Core\Database\Log $logger
    *   The logging object we want to use.
    */
   public function setLogger(Log $logger) {
@@ -410,7 +422,7 @@ public function setLogger(Log $logger) {
   /**
    * Gets the current logging object for this connection.
    *
-   * @return \Drupal\Core\Database\Log
+   * @return \Drupal\Core\Database\Log|null
    *   The current logging object for this connection. If there isn't one,
    *   NULL is returned.
    */
@@ -424,12 +436,12 @@ public function getLogger() {
    * This information is exposed to all database drivers, although it is only
    * useful on some of them. This method is table prefix-aware.
    *
-   * @param $table
+   * @param string $table
    *   The table name to use for the sequence.
-   * @param $field
+   * @param string $field
    *   The field name to use for the sequence.
    *
-   * @return
+   * @return string
    *   A table prefix-parsed string for the sequence name.
    */
   public function makeSequenceName($table, $field) {
@@ -441,10 +453,10 @@ public function makeSequenceName($table, $field) {
    *
    * The comment string will be sanitized to avoid SQL injection attacks.
    *
-   * @param $comments
+   * @param string[] $comments
    *   An array of query comment strings.
    *
-   * @return
+   * @return string
    *   A sanitized comment string.
    */
   public function makeComment($comments) {
@@ -483,10 +495,10 @@ public function makeComment($comments) {
    * Unless the comment is sanitised first, the SQL server would drop the
    * node table and ignore the rest of the SQL statement.
    *
-   * @param $comment
+   * @param string $comment
    *   A query comment string.
    *
-   * @return
+   * @return string
    *   A sanitized version of the query comment string.
    */
   protected function filterComment($comment = '') {
@@ -500,7 +512,7 @@ protected function filterComment($comment = '') {
    * query. All queries executed by Drupal are executed as PDO prepared
    * statements.
    *
-   * @param $query
+   * @param string|\Drupal\Core\Database\StatementInterface $query
    *   The query to execute. In most cases this will be a string containing
    *   an SQL query with placeholders. An already-prepared instance of
    *   StatementInterface may also be passed in order to allow calling
@@ -509,26 +521,36 @@ protected function filterComment($comment = '') {
    *   It is extremely rare that module code will need to pass a statement
    *   object to this method. It is used primarily for database drivers for
    *   databases that require special LOB field handling.
-   * @param $args
+   * @param array $args
    *   An array of arguments for the prepared statement. If the prepared
    *   statement uses ? placeholders, this array must be an indexed array.
    *   If it contains named placeholders, it must be an associative array.
-   * @param $options
-   *   An associative array of options to control how the query is run. See
-   *   the documentation for DatabaseConnection::defaultOptions() for details.
+   * @param array $options
+   *   An associative array of options to control how the query is run. The
+   *   given options will be merged with self::defaultOptions(). See the
+   *   documentation for self::defaultOptions() for details.
+   *   Typically, $options['return'] will be set by a default or by a query
+   *   builder, and should not be set by a user.
    *
    * @return \Drupal\Core\Database\StatementInterface|int|null
-   *   This method will return one of: the executed statement, the number of
-   *   rows affected by the query (not the number matched), or the generated
-   *   insert ID of the last query, depending on the value of
-   *   $options['return']. Typically that value will be set by default or a
-   *   query builder and should not be set by a user. If there is an error,
-   *   this method will return NULL and may throw an exception if
-   *   $options['throw_exception'] is TRUE.
+   *   This method will return one of the following:
+   *   - If either $options['return'] === self::RETURN_STATEMENT, or
+   *     $options['return'] is not set (due to self::defaultOptions()),
+   *     returns the executed statement.
+   *   - If $options['return'] === self::RETURN_AFFECTED,
+   *     returns the number of rows affected by the query
+   *     (not the number matched).
+   *   - If $options['return'] === self::RETURN_INSERT_ID,
+   *     returns the generated insert ID of the last query.
+   *   - If either $options['return'] === self::RETURN_NULL, or
+   *     an exception occurs and $options['throw_exception'] evaluates to FALSE,
+   *     returns NULL.
    *
    * @throws \Drupal\Core\Database\DatabaseExceptionWrapper
    * @throws \Drupal\Core\Database\IntegrityConstraintViolationException
    * @throws \InvalidArgumentException
+   *
+   * @see \Drupal\Core\Database\Connection::defaultOptions()
    */
   public function query($query, array $args = array(), $options = array()) {
     // Use default values if not already set.
@@ -628,6 +650,13 @@ protected function handleQueryException(\PDOException $e, $query, array $args =
    *
    * @return bool
    *   TRUE if the query was modified, FALSE otherwise.
+   *
+   * @throws \InvalidArgumentException
+   *   This exception is thrown when:
+   *   - A placeholder that ends in [] is supplied, and the supplied value is
+   *     not an array.
+   *   - A placeholder that does not end in [] is supplied, and the supplied
+   *     value is an array.
    */
   protected function expandArguments(&$query, &$args) {
     $modified = FALSE;
@@ -700,12 +729,12 @@ public function getDriverClass($class) {
   /**
    * Prepares and returns a SELECT query object.
    *
-   * @param $table
+   * @param string $table
    *   The base table for this query, that is, the first table in the FROM
    *   clause. This table will also be used as the "base" table for query_alter
    *   hook implementations.
-   * @param $alias
-   *   The alias of the base table of this query.
+   * @param string $alias
+   *   (optional) The alias of the base table of this query.
    * @param $options
    *   An array of options on the query.
    *
@@ -724,8 +753,10 @@ public function select($table, $alias = NULL, array $options = array()) {
   /**
    * Prepares and returns an INSERT query object.
    *
-   * @param $options
-   *   An array of options on the query.
+   * @param string $table
+   *   The table to use for the insert statement.
+   * @param array $options
+   *   (optional) An array of options on the query.
    *
    * @return \Drupal\Core\Database\Query\Insert
    *   A new Insert query object.
@@ -740,8 +771,10 @@ public function insert($table, array $options = array()) {
   /**
    * Prepares and returns a MERGE query object.
    *
-   * @param $options
-   *   An array of options on the query.
+   * @param string $table
+   *   The table to use for the merge statement.
+   * @param array $options
+   *   (optional) An array of options on the query.
    *
    * @return \Drupal\Core\Database\Query\Merge
    *   A new Merge query object.
@@ -757,8 +790,10 @@ public function merge($table, array $options = array()) {
   /**
    * Prepares and returns an UPDATE query object.
    *
-   * @param $options
-   *   An array of options on the query.
+   * @param string $table
+   *   The table to use for the update statement.
+   * @param array $options
+   *   (optional) An array of options on the query.
    *
    * @return \Drupal\Core\Database\Query\Update
    *   A new Update query object.
@@ -773,8 +808,10 @@ public function update($table, array $options = array()) {
   /**
    * Prepares and returns a DELETE query object.
    *
-   * @param $options
-   *   An array of options on the query.
+   * @param string $table
+   *   The table to use for the delete statement.
+   * @param array $options
+   *   (optional) An array of options on the query.
    *
    * @return \Drupal\Core\Database\Query\Delete
    *   A new Delete query object.
@@ -789,8 +826,10 @@ public function delete($table, array $options = array()) {
   /**
    * Prepares and returns a TRUNCATE query object.
    *
-   * @param $options
-   *   An array of options on the query.
+   * @param string $table
+   *   The table to use for the truncate statement.
+   * @param array $options
+   *   (optional) An array of options on the query.
    *
    * @return \Drupal\Core\Database\Query\Truncate
    *   A new Truncate query object.
@@ -825,8 +864,11 @@ public function schema() {
    * For some database drivers, it may also wrap the database name in
    * database-specific escape characters.
    *
+   * @param string $database
+   *   An unsanitized database name.
+   *
    * @return string
-   *   The sanitized database name string.
+   *   The sanitized database name.
    */
   public function escapeDatabase($database) {
     return preg_replace('/[^A-Za-z0-9_.]+/', '', $database);
@@ -839,8 +881,11 @@ public function escapeDatabase($database) {
    * For some database drivers, it may also wrap the table name in
    * database-specific escape characters.
    *
-   * @return
-   *   The sanitized table name string.
+   * @param string $table
+   *   An unsanitized table name.
+   *
+   * @return string
+   *   The sanitized table name.
    */
   public function escapeTable($table) {
     return preg_replace('/[^A-Za-z0-9_.]+/', '', $table);
@@ -853,8 +898,11 @@ public function escapeTable($table) {
    * For some database drivers, it may also wrap the field name in
    * database-specific escape characters.
    *
-   * @return
-   *   The sanitized field name string.
+   * @param string $field
+   *   An unsanitized field name.
+   *
+   * @return string
+   *   The sanitized field name.
    */
   public function escapeField($field) {
     return preg_replace('/[^A-Za-z0-9_.]+/', '', $field);
@@ -868,8 +916,11 @@ public function escapeField($field) {
    * DatabaseConnection::escapeTable(), this doesn't allow the period (".")
    * because that is not allowed in aliases.
    *
-   * @return
-   *   The sanitized field name string.
+   * @param string $field
+   *   An unsanitized alias name.
+   *
+   * @return string
+   *   The sanitized alias name.
    */
   public function escapeAlias($field) {
     return preg_replace('/[^A-Za-z0-9_]+/', '', $field);
@@ -894,10 +945,10 @@ public function escapeAlias($field) {
    * Backslash is defined as escape character for LIKE patterns in
    * Drupal\Core\Database\Query\Condition::mapConditionOperator().
    *
-   * @param $string
+   * @param string $string
    *   The string to escape.
    *
-   * @return
+   * @return string
    *   The escaped string.
    */
   public function escapeLike($string) {
@@ -907,7 +958,7 @@ public function escapeLike($string) {
   /**
    * Determines if there is an active transaction open.
    *
-   * @return
+   * @return bool
    *   TRUE if we're currently in a transaction, FALSE otherwise.
    */
   public function inTransaction() {
@@ -915,7 +966,10 @@ public function inTransaction() {
   }
 
   /**
-   * Determines current transaction depth.
+   * Determines the current transaction depth.
+   *
+   * @return int
+   *   The current transaction depth.
    */
   public function transactionDepth() {
     return count($this->transactionLayers);
@@ -924,8 +978,8 @@ public function transactionDepth() {
   /**
    * Returns a new DatabaseTransaction object on this connection.
    *
-   * @param $name
-   *   Optional name of the savepoint.
+   * @param string $name
+   *   (optional) The name of the savepoint.
    *
    * @return \Drupal\Core\Database\Transaction
    *   A Transaction object.
@@ -942,10 +996,11 @@ public function startTransaction($name = '') {
    *
    * This method throws an exception if no transaction is active.
    *
-   * @param $savepoint_name
-   *   The name of the savepoint. The default, 'drupal_transaction', will roll
-   *   the entire transaction back.
+   * @param string $savepoint_name
+   *   (optional) The name of the savepoint. The default, 'drupal_transaction',
+   *    will roll the entire transaction back.
    *
+   * @throws \Drupal\Core\Database\TransactionOutOfOrderException
    * @throws \Drupal\Core\Database\TransactionNoActiveException
    *
    * @see \Drupal\Core\Database\Transaction::rollback()
@@ -997,6 +1052,9 @@ public function rollback($savepoint_name = 'drupal_transaction') {
    *
    * If no transaction is already active, we begin a new transaction.
    *
+   * @param string $name
+   *   The name of the transaction.
+   *
    * @throws \Drupal\Core\Database\TransactionNameNonUniqueException
    *
    * @see \Drupal\Core\Database\Transaction
@@ -1026,8 +1084,8 @@ public function pushTransaction($name) {
    * back the transaction as necessary. If no transaction is active, we return
    * because the transaction may have manually been rolled back.
    *
-   * @param $name
-   *   The name of the savepoint
+   * @param string $name
+   *   The name of the savepoint.
    *
    * @throws \Drupal\Core\Database\TransactionNoActiveException
    * @throws \Drupal\Core\Database\TransactionCommitFailedException
@@ -1083,16 +1141,17 @@ protected function popCommittableTransactions() {
    * separate parameters so that they can be properly escaped to avoid SQL
    * injection attacks.
    *
-   * @param $query
+   * @param string $query
    *   A string containing an SQL query.
-   * @param $args
-   *   An array of values to substitute into the query at placeholder markers.
-   * @param $from
+   * @param int $from
    *   The first result row to return.
-   * @param $count
+   * @param int $count
    *   The maximum number of result rows to return.
-   * @param $options
-   *   An array of options on the query.
+   * @param array $args
+   *   (optional) An array of values to substitute into the query at placeholder
+   *    markers.
+   * @param array $options
+   *   (optional) An array of options on the query.
    *
    * @return \Drupal\Core\Database\StatementInterface
    *   A database query result resource, or NULL if the query was not executed
@@ -1103,7 +1162,7 @@ abstract public function queryRange($query, $from, $count, array $args = array()
   /**
    * Generates a temporary table name.
    *
-   * @return
+   * @return string
    *   A table name.
    */
   protected function generateTemporaryTableName() {
@@ -1122,15 +1181,17 @@ protected function generateTemporaryTableName() {
    * Note that if you need to know how many results were returned, you should do
    * a SELECT COUNT(*) on the temporary table afterwards.
    *
-   * @param $query
+   * @param string $query
    *   A string containing a normal SELECT SQL query.
-   * @param $args
-   *   An array of values to substitute into the query at placeholder markers.
-   * @param $options
-   *   An associative array of options to control how the query is run. See
-   *   the documentation for DatabaseConnection::defaultOptions() for details.
+   * @param array $args
+   *   (optional) An array of values to substitute into the query at placeholder
+   *   markers.
+   * @param array $options
+   *   (optional) An associative array of options to control how the query is
+   *   run. See the documentation for DatabaseConnection::defaultOptions() for
+   *   details.
    *
-   * @return
+   * @return string
    *   The name of the temporary table.
    */
   abstract function queryTemporary($query, array $args = array(), array $options = array());
@@ -1142,6 +1203,9 @@ abstract function queryTemporary($query, array $args = array(), array $options =
    * instance, there could be two MySQL drivers, mysql and mysql_mock. This
    * function would return different values for each, but both would return
    * "mysql" for databaseType().
+   *
+   * @return string
+   *   The type of database driver.
    */
   abstract public function driver();
 
@@ -1155,7 +1219,7 @@ public function version() {
   /**
    * Determines if this driver supports transactions.
    *
-   * @return
+   * @return bool
    *   TRUE if this connection supports transactions, FALSE otherwise.
    */
   public function supportsTransactions() {
@@ -1167,7 +1231,7 @@ public function supportsTransactions() {
    *
    * DDL queries are those that change the schema, such as ALTER queries.
    *
-   * @return
+   * @return bool
    *   TRUE if this connection supports transactions for DDL queries, FALSE
    *   otherwise.
    */
@@ -1199,7 +1263,7 @@ abstract public function createDatabase($database);
    * overridable lookup function. Database connections should define only
    * those operators they wish to be handled differently than the default.
    *
-   * @param $operator
+   * @param string $operator
    *   The condition operator, such as "IN", "BETWEEN", etc. Case-sensitive.
    *
    * @return
@@ -1226,7 +1290,7 @@ public function commit() {
   }
 
   /**
-   * Retrieves an unique id from a given sequence.
+   * Retrieves an unique ID from a given sequence.
    *
    * Use this function if for some reason you can't use a serial field. For
    * example, MySQL has no ways of reading of the current value of a sequence
@@ -1234,9 +1298,9 @@ public function commit() {
    * value. Or sometimes you just need a unique integer.
    *
    * @param $existing_id
-   *   After a database import, it might be that the sequences table is behind,
-   *   so by passing in the maximum existing id, it can be assured that we
-   *   never issue the same id.
+   *   (optional) After a database import, it might be that the sequences table
+   *   is behind, so by passing in the maximum existing ID, it can be assured
+   *   that we never issue the same ID.
    *
    * @return
    *   An integer number larger than any number returned by earlier calls and