On using auto in code examples

[Georg Wrede]

I've been doing some programming, as opposed to telling everyone how the 
language should be. The role change has given me a new angle to the 
existing documentation.

Using auto in examples shows of course the "ease and flexibility" of the 
language. But, it does make the examples less efficient for the purpose 
of teaching the language, or showing quickly and accurately how and what 
to do!

Of course you save some keystrokes, maybe some time by not having to 
remember what the exact type is. But in real life, in most cases you 
have to know the type anyway, unless we're talking about some tight 
routines where something is defined, used and forgotten -- all within a 
few lines of code.

I think all examples should use proper types, and then maybe some 
separate page could explain that here and there you _could_ use auto. 
And explain also the perils and gotchas of doing so -- which is 
impossible if auto is spread all over the examples.

Also, having auto all over the place /does/ give the new reader a robust 
impression that using auto is the Canonical Way of writing D code.

Another deceptive thing is the foreach syntax. Even for one who has been 
here from the start, and who has participated thoroughly in the debate 
about that particular syntax, seeing the examples makes one stop for a 
moment and wonder where is this [loop variable] introduced, and what 
might its type be.

Microsoft being hopeles, I'd like everyone else to have their examples, 
and later their code, to not contain gratuituous mental short-cuts that 
will only come back later on to bite one [where it really hurts].

----

With this new angle to the docs, I'm getting the impression that Ddoc is 
good for project code documentation _only_, and not for creating 
reference litterature. Seems it encourages the source code writers to 
skip "the too obvious", and at the same time writing fluent and 
sufficient doc-comments may seem tedious. In other words, it seems quite 
demanding to write such Ddoc documentation that one doesn't need to 
browse the actual source code in another window.

(Of course Ddoc is better than nothing, and certainly better than what 
other languages have, but we should not lull ourselves into believing 
its mere existence and casual use is a panacea for documentation 
shortcomings.)