Yes
---
Oleg

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?


On 26 August 2012 04:54, Oleg Kuporosov <Oleg.Kuporosov@gmail.com> wrote:

>
> Yes
> ---
> Oleg
>
>

"Manu" <turkeyman@gmail.com> wrote in message news:mailman.1410.1345976415.31962.digitalmars-d@puremagic.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?



On 26 August 2012 04:54, Oleg Kuporosov <Oleg.Kuporosov@gmail.com> wrote:


  Yes
  ---
  Oleg




+1.

The documentation should be there for clarity.

-=mike=-

On Sunday, 26 August 2012 at 10:32:37 UTC, Mike James wrote:
>
> "Manu" <turkeyman@gmail.com> wrote in message news:mailman.1410.1345976415.31962.digitalmars-d@puremagic.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?
>
>
>
> On 26 August 2012 04:54, Oleg Kuporosov <Oleg.Kuporosov@gmail.com> wrote:
>
>
>   Yes
>   ---
>   Oleg
>
>
>
>
> +1.
>
> The documentation should be there for clarity.
>
> -=mike=-

+2
As a very inexperienced D user, I find the use of auto in the
documentation frustrating too.

Cheers,

Craig

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.

On 8/26/12 8:35 AM, Craig Dillabaugh wrote:
> On Sunday, 26 August 2012 at 10:32:37 UTC, Mike James wrote:
> +2
> As a very inexperienced D user, I find the use of auto in the
> documentation frustrating too.
>
> Cheers,
>
> Craig

I'm torn on this. The arguments make sense; on the other hand, people will in all likelihood write their own code in the style promoted by the doc examples.

How about this - use auto for code samples, but not for documenting function return types (except Voldemort)?


Andrei

Andrei Alexandrescu:

> I'm torn on this. The arguments make sense; on the other hand, people will in all likelihood write their own code in the style promoted by the doc examples.
>
> How about this - use auto for code samples, but not for documenting function return types (except Voldemort)?

Generally I'd like the documentation examples to not use auto, because this makes the examples more clear and less easy to misunderstand.

Programmers are lazy, so I think D programmers learn quickly how much handy 'auto' is. So I think the risk you refer to of them not using auto in their code is low.

Teachers know that usually you have to teach people the less handy things, because students learn the lazy things more quickly. Example: in D.learn someone was saying that adding the immutable/const/pure/nothrow annotations is boring.

In my code I use often auto for variable defined inside functions, but usually I write the real return type of functions, because this helps me understand better the code I am working one, it's more self-documenting. Even in Haskell, where there is a powerful global type inferencer, you usually write down the types of inputs and outputs of functions, for similar reasons.

Bye,
bearophile

On 8/22/12 8:36 AM, Dmitry Olshansky wrote:
> The discussion around new unified API for digest hash functions has
> subdued, just in time as the review period has ended.
>
> The voting for std.digest package starts today and ends on 29 August.
>
> Rules are simple: reply in this thread with definite "YES" or "NO" on
> whether this package should go into Phobos. Including descriptive short
> notes is appreciated (esp. the NO ones).
>
>
> Latest locations of docs and source:
>
> Code: (location changed!)
> https://github.com/jpf91/phobos/tree/newHash/std/digest
> https://github.com/jpf91/phobos/compare/master...newHash
>
> Docs: (location changed!)
> http://dl.dropbox.com/u/24218791/d/phobos/std_digest_digest.html
> http://dl.dropbox.com/u/24218791/d/phobos/std_digest_md.html
> http://dl.dropbox.com/u/24218791/d/phobos/std_digest_sha.html
> http://dl.dropbox.com/u/24218791/d/phobos/std_digest_crc.html

I couldn't make time for a review during the window, apologies. Nevertheless I'd like to make a pass in hope that a few issues can be fixed before the code is publicly released.

* No need for start() after default construction in the documentation example of CRC32. BTW the documentation of start() suggests that it _must_ be called even right after default construction, is that the case?

* In the template interface, no need for void peek(ref ...). Returning by value is fine due to the RVO. Same about finish() - just keep the functions returning by value.

* This example:

copy(oneMillionRange, &ctx); //Note: You must pass a pointer to copy!

suggests we're doing something wrong. I think a better solution would be to have copy() take the target range by "auto ref", and institute this passing convention as a general rule for output ranges.

* s/digestType/DigestType/

* s/isDigestable/isDigestible/

* s/startDigest/makeDigest/ - but then again I wonder if requiring start() after default construction is needed.

* s/asArray/asStaticArray/. Better yet, we should include this primitive in std.conv. Then we get to use to!(ubyte[16])(dynarray).

* The fact that digests aren't unique is trivial by the pigeonhole principle, and should not be listed as a bug (the BUGS: tag implies bugs in the implementation). It's more interesting if a document can be altered to produce a specific digest. If that's what you meant, include a link to the appropriate work.

* I don't think the aliases for WrapperDigest!Xyz should be defined. Just call that Digest!Xyz and have people use it. It's about as short as the aliases.

I vote for inclusion whether or not the points above are addressed, but of course it would be great if they were minded before release. Apologies for the late review.



Andrei

One more thing - for future work, it would be great to have a function a la mcookie, see http://linux.about.com/library/cmd/blcmdl1_mcookie.htm.

Andrei

On Sunday, August 26, 2012 10:14:14 Andrei Alexandrescu wrote:
> How about this - use auto for code samples, but not for documenting function return types (except Voldemort)?

I tend to agree with this. If a function needs to return auto in order to be reasonable (e.g. it has to because of Voldemort types, it's return type is too complicated to _not_ be auto, or its return type varies), then it should return auto. Otherwise, we should probably be explicit about the return type. However, I think that the code samples should still generally use auto, because that's the style that we think should be used in actual code.

- Jonathan M Davis