www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.bugs - [Issue 16299] New: Documentation for Phobos needs to warn about


          Issue ID: 16299
           Summary: Documentation for Phobos needs to warn about
           Product: D
           Version: D2
          Hardware: All
                OS: All
            Status: NEW
          Severity: enhancement
          Priority: P2
         Component: dlang.org
          Assignee: nobody puremagic.com
          Reporter: wyatt.epp gmail.com

The anomalous effects of autodecoding for Phobos functions are _effectively_
undocumented.  This means an innocent user has no warning that something like
std.algorithm.iteration.permutations will fail on an array of char[] (a very
common built-in type).  This is bad.

Possible fixes:
- Add warnings (with text _and_ links) that using char[] is going to screw
    If using a char[] is going to break something, that should be mentioned in
the documentation for it.  There at least needs to be a generic warning that
stands out visually and links to further information on the autodecoding
problem and how to work around it.

- Add examples that show affected templates used on char[] and dchar[]:
    Most of the examples are conscripted unit tests using integers.

- Have the compiler explain the actual problem:
    Ugly? Maybe. Special casing is bad? Sure. But the current error is really
obtuse when you can do exactly what the example does only with a different type
and get "cannot deduce function from argument types".  That's way out of left

- Make it actually work like it should:
    Especially if the input is known at compile time, autodecoding shouldn't
even be a problem.  But even at runtime, this should just work without fuss. 
Users shouldn't have to hunt down the documentation for template constraints if
they're not writing range types of their own; we made them grey because most
people _can_ ignore them.

See Also: 

Jul 19 2016