drupal_rewrite_settings()'s documentation is incorrect

API page: https://api.drupal.org/api/drupal/includes%21install.inc/function/drupal...

Updated: Comment #0

Problem/Motivation

(Why the issue was filed, steps to reproduce the problem, etc.)
I've been writing a custom installation profile. One of its tasks (in the everyday sense of the word) is to accept a title and color for the Environment Indicator module and then write them into the settings.php file, where they properly belong.

I'm relatively new to this level of Drupal, but drupal_rewrite_settings() seemed like an intuitive and natural choice for manipulating the settings file. It's description read: "Replaces values in settings.php with values in the submitted array." Not quite exactly what I wanted to do, which was add values to settings.php, but a cursory glance over the code showed me that it did just that as well. So I used it.

The problem was that, while it was adding my values to settings.php, it was also removing the $databases and $drupal_hash_salt. Upon closer inspection of the code, I noticed lines 591 and 604 of the containing file. Turns out that drupal_rewrite_settings() doesn't actually rewrite the settings file. Instead reads from default.settings.php, rewrites it in memory, and saves the resulting buffer to settings.php.

Because settings.php is never read from, this function doesn't actually update anything. It simply overwrites whatever was already there, always using default.settings.php as a starting point.

Proposed resolution

Ideally, the function would be modified to make it more reusable. It looks like this has already been done for D8, where drupal_rewrite_settings() has received considerable attention.

I think then that appropriate thing for D7 is to flesh out the documentation a little bit. We should clarify that drupal_rewrite_settings() reads from default.settings.php only. In the future, developers like me who need to add to settings.php during installation of Drupal will find some other way to do it.

Remaining tasks

Clarify or rewrite the documentation in install.inc around lines 584-589.