Phobos examples and auto

[Vladimir Panteleev]

On Sat, 05 Nov 2011 21:49:11 +0200, Andrei Alexandrescu  
<SeeWebsiteForEmail at erdani.org> wrote:

> It's tricky. One simple fact that's been verified again and again is  
> that documentation examples tend to be used a lot. They effectively are  
> powerful style influencers for people learning the language.
>
> If we avoid "auto" in documentation examples but we do use it in  
> everyday code, we effectively foster a style that's foreign and  
> non-idiomatic to newcomers.
>
> Sample code should mimic real code. If real code would use auto, sample  
> code should use auto.

I find that I frequently need to look up the return type of a function  
when the example doesn't mention it. One could argue that documentation  
examples shouldn't be considered as "sample code" and thus expected to be  
idiomatic, because they're highly contextual. Either way, a possible  
compromise could be to use the return type when it's highly likely that  
the user will want to use the type in their programs (class field or  
global variable declarations). For example, time values occur frequently  
as non-local variables, while the results of functional programming  
functions (map/reduce/etc.) do not.

-- 
Best regards,
  Vladimir                            mailto:vladimir at thecybershadow.net