Change drupal_static('name', whatever, TRUE) function comments

Problem & Proposed resolution:

Comments for 3rd parameter of drupal_static() should be changed. See original report for a reason why.

For D8 it is planned to remove the function, but in D7 the function will live on, so the documentation is important. Patch applies do D7 too (with -p2 flag)

Remaining tasks, API changes

none. (This patch intends no changes whatsoever, except for more clarity.)

Original report by hefox

Didn't see anything specially about this and saw that d7 had issues under review to change drupal_static, so figured file here and accept my "duplicate" if it is.

function &drupal_static($name, $default_value = NULL, $reset = FALSE) {
  static $data = array(), $default = array();
  // First check if dealing with a previously defined static variable.
  if (isset($data[$name]) || array_key_exists($name, $data)) {
    // Non-NULL $name and both $data[$name] and $default[$name] statics exist.
    if ($reset) {
      // Reset pre-existing static variable to its default value.
      $data[$name] = $default[$name];
    }
    return $data[$name];
  }
  // Neither $data[$name] nor $default[$name] static variables exist.
  if (isset($name)) {
    if ($reset) {
      // Reset was called before a default is set and yet a variable must be
      // returned.
      /////// This!!! why is it doing this?! ////////
      return $data;
    }
    // First call with new non-NULL $name. Initialize a new static variable.
    $default[$name] = $data[$name] = $default_value;
    return $data[$name];
  }
  // Reset all: ($name == NULL). This needs to be done one at a time so that
  // references returned by earlier invocations of drupal_static() also get
  // reset.
  foreach ($default as $name => $value) {
    $data[$name] = $value;
  }
  // As the function returns a reference, the return should always be a
  // variable.
  return $data;
}

It's very unexpected behavior and easily leads to bugs. #2314173: Something is overriding the static for workbench_moderation_transitions Is it really suppose to be working that way? It means reset works completily differently if called at different points.