Worst Phobos documentation evar!

[H. S. Teoh via Digitalmars-d]

On Mon, Dec 29, 2014 at 09:10:15PM +0000, bachmeier via Digitalmars-d wrote:
> On Monday, 29 December 2014 at 17:38:42 UTC, H. S. Teoh via Digitalmars-d
> wrote:
> >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.
> 
> That's not something we should assume a new D user will know. Someone
> with a few years of C++ experience will probably be okay, but that's
> kind of my point - the documentation shouldn't require that
> background. I can imagine someone seeing examples that use auto with
> ranges and then asking "Now what?" Those are the frustrations that
> make users give up on the language.

You're missing the point. The user *should not* know what the returned
type is! (And cannot know, when it's a local struct inside the function
that has no name outside.) The type is *intentionally* opaque, because
the whole point of using such a construct is to prevent user code from
having explicit dependencies on the actual type. Explicitly documenting
the precise type defeats the purpose completely, and we might as well go
back to C and use ExplicitIterator*, AnotherExplicitIterator*,
YetAnotherExplicitIterator*, with 150 different structs defining 150
functionally-equivalent things that only just happen to be implemented
differently.

Of course, the flip side of that, is that probably all references to
range return types (or any other Voldemort / opaque return types, for
that matter) should to hyperlink to an explanation for what kind of
operations the returned type supports. I don't think the issue you bring
up will be a problem if the function documentation says something along
the lines of:

	Returns: A [forward range] of integers.

where [forward range] is a hyperlink to a definition of what a forward
range is and what it does.

In fact, here's another low-hanging fruit for wanna-be Phobos
contributors: add said hyperlinks to all the range-based functions in
Phobos. Or, better yet, since these things are so common in Phobos, add
a macro that contains the hyperlink for each type of range, and just
write $(INPUT_RANGE), $(FORWARD_RANGE), etc., instead in all places in
the documentation where it occurs.


T

-- 
PNP = Plug 'N' Pray