On using auto in code examples

[Sean Kelly]

Georg Wrede wrote:
> 
> 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.

Agreed on both counts.  I've even been bitten by the foreach issue once 
or twice, when I wanted to preserve the index as a position count.

> 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.

It is, but the presence of any in-code documentation feature is a win 
IMO.  If I had to document API code in a purely external manner I'd 
never do it.

> (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.)

Agreed.


Sean