In most cases, the return types are just ranges, but because they're constructed by the algorithm, the algorithm creates its own range type. So, generally, all you need to know is that a range is being returned. But even then, you run into some issues where you need to do stuff like run the returned range through array() to get something useable - depending on what you're doing with it. Regardless of the return type though, std.algorithm is definitely a prime example of how auto is your friend. That way you often don't have to care all that much about what the return type really looks like.
That paragraph would have been immensely useful to me a few months ago.
However, the documentation on it is obviously ugly. It really should give the programmer exactly what they need to use the function and nothing more. As it stands, you have to really want to use it to figure it out. Personally, I think that it's well worth it - std.algorithm is fantastic - but the documentation is nowhere near as straightforward as it should be (even if using the functions is actually pretty straightforward in most cases).
Agreed. I'm also a big fan of examples as it's very easy to look at an example and get something working. Then, once you see it work and get somewhat of an understanding, you can dig deeper into the details to learn more.
Casey