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