[Issue 21014] New: aa.byKeyValue, byKey, byValue very under-documented

[d-bugmail at puremagic.com]

https://issues.dlang.org/show_bug.cgi?id=21014

          Issue ID: 21014
           Summary: aa.byKeyValue, byKey, byValue very under-documented
           Product: D
           Version: D2
          Hardware: x86
                OS: Mac OS X
            Status: NEW
          Severity: enhancement
          Priority: P1
         Component: dlang.org
          Assignee: nobody at puremagic.com
          Reporter: schveiguy at yahoo.com

e.g.:

https://github.com/dlang/druntime/blob/d3dfa0778fbad77482b0ae8e7e528b55aa417c19/src/object.d#L2491-L2497

```
/***********************************
 * Returns a forward range over the key value pairs of the associative array.
 * Params:
 *      aa =     The associative array.
 * Returns:
 *      A forward range.
 */
```

No indication of what the range's front returns, if items are returned by
reference, if changes to the AA invalidate the type returned by front, etc.

In fact, the front type is a voldemort type with a ref accessor for both key
and value (named as such).

Putting in documentation as to what the range provides would be helpful. I
shouldn't have to look at the source.

--