Phobos examples and auto

[Jesse Phillips]

On Sat, 05 Nov 2011 17:42:59 +0000, Steve Teale wrote:

> There's a growing tendency in Phobos documentation to use auto.
> 
> auto now = Clock.currTime();
> 
> Now I can understand that when the RHS is some obscure template, whose
> type might not be immediately obvious, the user should possibly be
> encouraged to RTFM. But if the outcome is deterministic I just have the
> feeling that documentation should provide information rather than hiding
> it.
> 
> OK, in Jonathan's example, this is preceded by a sentence that says that
> the result is a SysTime. But the auto made me forget, and wonder what it
> was, rather than reinforcing the preceding sentence.
> 
> I realize that this is probably a trivial point, but at the same time,
> in documentation, clarity is wonderful.
> 
> Steve

I find it interesting that the exception is given to the "obscure 
template, whose type might not be immediately obvious." For one thing 
such types are fairly common in Phobos. For another, doesn't that just 
mean that once the type gets complicated you don't care anymore and 
instead just care about what you can do with what is returned?

I think examples should make use of auto, unless the result isn't going 
to be used in the example. But more importantly I think all non-template 
functions which use auto return types should have DDoc show the specific 
type.