On Sat, 05 Nov 2011 15:49:11 -0400, Andrei Alexandrescu
<seewebsiteforem...@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
