documentation misleading

Maybe I'm misinterpreting things, but there is a portion of the API.txt file that is confusing.

The section labeled "Altering the Replacement Values", last line of the last paragraph, says

"The return value will be an array with tokens as keys to their own replacement values."

When I first read this, I expected something like...

array(
  token1 => value1,
  token2 => value2,
  etc.
);

Instead, the array (or more accurately, object) looks like...

stdClass Object {
  [tokens] => array(
    [0] => mytoken1,
    [1] => mytoken2
  ),
  [values] => array(
    [0] => value1,
    [1] => value2,
  )
}

Perhaps the simplest way to handle this would be to add an example to the documentation.