• d-bugmail puremagic.com (31/31) Jul 05 2020 https://issues.dlang.org/show_bug.cgi?id=21014

d-bugmail puremagic.com writes:

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 puremagic.com
          Reporter: schveiguy 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.

--