On 8/26/12 7:14 AM, Andrei Alexandrescu wrote:
> How about this - use auto for code samples, but not for documenting
> function return types (except Voldemort)?

Pie-in-the-sky dream: DDOC would advance enough to show a hover hint over the "auto" keyword with the computed type.

On Tue, Aug 28, 2012 at 1:19 AM, David Gileadi <gileadis@nspmgmail.com>wrote:

> On 8/26/12 7:14 AM, Andrei Alexandrescu wrote:
>
>> How about this - use auto for code samples, but not for documenting function return types (except Voldemort)?
>>
>
> Pie-in-the-sky dream: DDOC would advance enough to show a hover hint over the "auto" keyword with the computed type.
>

I was just thinking the same thing but not sure what would happen with printed versions of the documentation (that would be a solveable problem though I think).

On 8/26/2012 7:14 AM, Andrei Alexandrescu wrote:
> On 8/26/12 8:35 AM, Craig Dillabaugh wrote:
>> On Sunday, 26 August 2012 at 10:32:37 UTC, Mike James wrote:
>> +2
>> As a very inexperienced D user, I find the use of auto in the
>> documentation frustrating too.
>>
>> Cheers,
>>
>> Craig
>
> I'm torn on this. The arguments make sense; on the other hand, people will in
> all likelihood write their own code in the style promoted by the doc examples.
>
> How about this - use auto for code samples, but not for documenting function
> return types (except Voldemort)?

I think there need to be explicit types in the doc so people can click on a link to them and see what they are.

On Sunday, 26 August 2012 at 10:32:37 UTC, Mike James wrote:
>
> "Manu" <turkeyman@gmail.com> wrote in message news:mailman.1410.1345976415.31962.digitalmars-d@puremagic.com...
> Looks good, though one thing annoys me as always throughout the D docs, liberal use of auto can make them very difficult to understand.
> auto result = hash.finish();From the examples where this appears, I have absolutely no idea what 'result' could possibly be and what I can do with it, and you're forcing me to go and dig further for that information (waste of time).
> Surely there would be no harm in just writing the type there for clarity?

I also find this very annoying. I'm trying to learn what types different methods return but i have no idea what is beneath an auto type. Explicit types would aid learning so much more! I understand the need for the auto keyword as a shortcut for productivity but you need to understand the underlying type before you're really comfortable with auto. I would like to see all examples in the language reference using explicit types purely for clarity.

On 2012-08-28 23:29, Walter Bright wrote:

> I think there need to be explicit types in the doc so people can click
> on a link to them and see what they are.

I should work with "auto" as well.

-- 
/Jacob Carlborg

On 2012-08-26 12:19, Manu wrote:
> Looks good, though one thing annoys me as always throughout the D docs,
> liberal use of auto can make them very difficult to understand.
>
> auto  result = hash.finish();
>
>  From the examples where this appears, I have absolutely no idea what
> 'result' could possibly be and what I can do with it, and you're forcing
> me to go and dig further for that information (waste of time).
> Surely there would be no harm in just writing the type there for clarity?
>
> <rant>
> I'd personally like to see auto abolished, or at least heavily
> discouraged for the sake of clarity from code examples throughout the
> docs. I'm constantly having to chase up what auto's may resolve to when
> reading examples >_<
> You may argue this demonstrated un-idiomatic code, and my trouble is due
> to inexperience; I ask, who is most likely to be reading docs?

I think that in general "auto" shouldn't be used. In some case auto can be used, i.e. where you don't care/don't need to know the actual type and using duck typing instead. If we compare this with OO it would be like using an interface instead of the actual type. I guess in std.algorithm it would be ok to use "auto".

-- 
/Jacob Carlborg