Phobos examples and auto

[Steven Schveighoffer]

On Sat, 05 Nov 2011 15:49:11 -0400, Andrei Alexandrescu  
<SeeWebsiteForEmail at erdani.org> wrote:

> On 11/5/11 1:48 PM, Walter Bright wrote:
>> On 11/5/2011 10:42 AM, 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.
>>
>> I agree.
>
> 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.

The compiler's generating the docs, and I know that it's not actually  
compiling the examples, but here's my suggestion (if it's possible):

1. The compiler determine what the actual "auto" type would be.
2. If the user hovers the mouse over auto, display a tooltip with the  
auto-determined name
3. There should be a button to turn all autos into their normal types.

Sould feasible?

As a bonus, it would actually verify the examples are valid code (even if  
they aren't semantically valid) ;)

-Steve