On 26 August 2012 16:43, Johannes Pfau
<nospam@example.com> wrote:
Am Sun, 26 Aug 2012 13:19:35 +0300
schrieb Manu <turkeyman@gmail.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?
>
> <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?
>
OK, I'll fix this if std.digest is accepted into phobos.
However, in this example auto is not just used for convenience, it has
an actual use case:
As documented here
http://dl.dropbox.com/u/24218791/d/phobos/std_digest_digest.html#ExampleDigest
(finish method) the type returned by finish can differ between different
hash implementations. It's always a static array of ubyte, but for crc
it's ubyte[4] for sha1 it's ubyte[20] and for md5 it's ubyte[16]. So
in templated methods, auto is more generic than hardcoding a type. The
equivalent to auto is using digestType!Digest, so
auto result = hash.finish();
digestType!(typeof(hash)) result = hash.finish();
are equivalent. But
ubyte[4] result = hash.finish();
does only work if hash is a CRC32 digest. It does not work for md5, sha1
digests, etc.
But I agree that examples are easier to read without auto, so I'll
change them to use the explicit type where possible.
Case in point, look how much information you just gave us that is completely obscured by 'auto' :)
My suggestion, simplify the example, or, at least the example associated with the direct function documentation:
auto md5 = digest!MD5( "The quick brown fox jumps over the lazy dog");
auto sha1 = digest!SHA1( "The quick brown fox jumps over the lazy dog");
auto crc32 = digest!CRC32("The quick brown fox jumps over the lazy dog");
Those autos can be ubyte[n].
Though that said, looking at the API doc for finish(), it appears to return a dynamic array, not a static array as you say... so ubyte[] could be used everywhere, and that would be nice and clear?