diff --git a/core/includes/install.inc b/core/includes/install.inc
index 088413a..4c3cc4b 100644
--- a/core/includes/install.inc
+++ b/core/includes/install.inc
@@ -192,7 +192,18 @@ function drupal_rewrite_settings($settings = array()) {
         // Write the new value to settings.php in the following format:
         //    $[setting] = '[value]'; // [comment]
         $setting = $settings[$variable_name];
-        $buffer .= '$' . $variable_name . ' = ' . var_export($setting['value'], TRUE) . ';';
+        // Add special handling for the $databases setting to improve readability and to
+        // match the format of the database settings documentation in settings.php.
+        if ($variable_name == 'databases') {
+          foreach ($setting['value'] as $db_name => $values) {
+            foreach ($values as $db_role => $values) {
+              $buffer .= '$' . "databases['$db_name']['$db_role'] = " . var_export($values, TRUE) . ";";
+            }
+          }
+        }
+        else {
+          $buffer .= '$' . $variable_name . " = " . var_export($setting['value'], TRUE) . ";";
+        }
         if (!empty($setting['comment'])) {
           $buffer .= ' // ' . $setting['comment'];
         }
diff --git a/sites/default/default.settings.php b/sites/default/default.settings.php
index b2fbc90..fac5d35 100644
--- a/sites/default/default.settings.php
+++ b/sites/default/default.settings.php
@@ -64,12 +64,12 @@
  * similar to the following:
  * @code
  * array(
- *   'driver' => 'mysql',
  *   'database' => 'databasename',
  *   'username' => 'username',
  *   'password' => 'password',
  *   'host' => 'localhost',
  *   'port' => 3306,
+ *   'driver' => 'mysql',
  *   'prefix' => 'myprefix_',
  *   'collation' => 'utf8_general_ci',
  * );
@@ -116,11 +116,11 @@
  * For a single database configuration, the following is sufficient:
  * @code
  * $databases['default']['default'] = array(
- *   'driver' => 'mysql',
  *   'database' => 'databasename',
  *   'username' => 'username',
  *   'password' => 'password',
  *   'host' => 'localhost',
+ *   'driver' => 'mysql',
  *   'prefix' => 'main_',
  *   'collation' => 'utf8_general_ci',
  * );
@@ -191,24 +191,30 @@
  * Database configuration format:
  * @code
  *   $databases['default']['default'] = array(
- *     'driver' => 'mysql',
  *     'database' => 'databasename',
  *     'username' => 'username',
  *     'password' => 'password',
  *     'host' => 'localhost',
+ *     'port' => '',
+ *     'namespace' => 'Drupal\\Core\\Database\\Driver\\mysql',
+ *     'driver' => 'mysql',
  *     'prefix' => '',
  *   );
  *   $databases['default']['default'] = array(
- *     'driver' => 'pgsql',
  *     'database' => 'databasename',
  *     'username' => 'username',
  *     'password' => 'password',
  *     'host' => 'localhost',
+ *     'port' => '',
+ *     'namespace' => 'Drupal\\Core\\Database\\Driver\\pgsql',
+ *     'driver' => 'pgsql',
  *     'prefix' => '',
  *   );
  *   $databases['default']['default'] = array(
- *     'driver' => 'sqlite',
  *     'database' => '/path/to/databasefilename',
+ *     'namespace' => 'Drupal\\Core\\Database\\Driver\\sqlite',
+ *     'driver' => 'sqlite',
+ *     'prefix' => '',
  *   );
  * @endcode
  */