What is the correct use of auto?

[Robert Fraser]

Unknown W. Brackets wrote:
> Surely; but I think cases where you have to deal with another API (e.g. 
> of another library) are actually very frequent.  Documenting them in 
> your documentation may neither be prudent nor helpful.
> 
> Most of the time, using auto for a return type is bad.  However, it 
> might be good - especially with a comment like this:
> 
> // Version 1 and 2 return different types here.
> // Version 1 returns "Xyz" and version 2 returns "Abc".
> 
> Or also:
> 
> // The type returned here may change at some point.
> // It will always have a "runFromGodzilla" method, which is the only one
> // that is useful in this version of the library.
> 
> And similar.  Undocumented, or poorly documented, examples are another 
> problem.  Telling me that your car runs badly without gas doesn't mean 
> tell me anything about oil.  Sure, they may both be things to improve 
> with your car.
> 
> I didn't say my example was perfect, but it isn't a wrong or confusing 
> use of auto.  If I were really documenting the use of stderr, I'd 
> probably show mainly strings, much more in the way of formatting, etc. 
> Likely I would also describe why and how it is best for error messages, 
> even possibly a basic primer on how to pipe it properly.
> 
> Sorry I did not give a fully developed example.  It was merely to 
> illustrate, since I'm sure anyone participating in this conversation 
> understands stderr.
> 
> I frankly hate Mango/Tango's abuse of the (), and etc.  I think it makes 
> for hard to read code, confuses beginners, and isn't even clean.  I 
> realize many disagree and this is obviously a personal opinion.
> 
> But I think anyone would agree that isn't a good example and auto has 
> been misused there out of laziness.  I just think that saying "auto is 
> wrong always" is very likely incorrect.
> 
> -[Unknown]

I agree with everything you said here. My initial statement of "auto is 
always wrong in examples" was too broad, but that's from experience 
(mostly with Mango/Tango examples, but I don't mean to pick on them 
here) that used auto in confusing ways. I guess what I'm trying to say 
is that in examples, "air on the side of caution" and use auto only when 
the type is either very clear or has no bearing on the example.

So, basically, what you just said.