Worst Phobos documentation evar!

[H. S. Teoh via Digitalmars-d]

On Sun, Dec 28, 2014 at 11:14:56PM +0000, bachmeier via Digitalmars-d wrote:
> On Sunday, 28 December 2014 at 19:33:25 UTC, eles wrote:
> >On Sunday, 28 December 2014 at 17:10:21 UTC, bachmeier wrote:
> >>On Sunday, 28 December 2014 at 02:55:39 UTC, Xinok wrote:
> >>>On Sunday, 28 December 2014 at 01:00:49 UTC, Walter Bright wrote:
> >
> >>That's a good idea. I propose rule #1: Under no circumstances will
> >>auto be allowed in any examples. The compiler should even reject
> >>files in which they appear. One of the most frustrating things is to
> >>read documentation with type T (completely uninformative) followed
> >>by an example with auto.
> >
> >Speaking of which:
> >
> >http://forum.dlang.org/post/dzuhxuoqmpzrumwcmtqj@forum.dlang.org
> >
> >http://dlang.org/phobos/std_typecons.html#.scoped
> >
> >http://ddili.org/ders/d.en/destroy.html
> >
> >(Thanks, Ali)
> 
> That's something that I was not aware of, but it's different from what
> I was referring to. Perhaps the rule should be that auto can only be
> used if it matters and if there is an explanation of why it matters.

Most Phobos range functions return opaque types that the user should not
depend on (even if the type is nameable), since the point of the range
API is to have user code Just Work(tm) without needing to know the
actual type of the returned object.

What *is* very important in documentation, though, is to indicate what
kind of range is returned. It's very frustrating, for example, if the
function returns a forward range, but the documentation tells you
nothing about what the return type can do!


T

-- 
MSDOS = MicroSoft's Denial Of Service