code review 10478048: hash: tweak the package docs

hash: tweak the package docs
No semantic change.
I found the wording distracting in a couple of instances and was moved to improve it.

[r, 2013-06-24 23:09:42]

Hello golang-dev@googlegroups.com,

I'd like you to review this change to
https://code.google.com/p/go

[bradfitz, 2013-06-24 23:32:47]

https://codereview.appspot.com/10478048/diff/1/src/pkg/hash/hash.go
File src/pkg/hash/hash.go (right):

https://codereview.appspot.com/10478048/diff/1/src/pkg/hash/hash.go#newcode13
src/pkg/hash/hash.go:13: // (It is declared here by embedding the io.Writer
interface.)
We're now teaching people how Go works in the standard library API docs?

https://codereview.appspot.com/10478048/diff/1/src/pkg/hash/hash.go#newcode21
src/pkg/hash/hash.go:21: // Reset resets the Hash to its initial state, as if
zero bytes have
I would just say:

// Reset resets the Hash to its initial state.

The whole "as if zero bytes have been written" sounds too close to "like calling
Write(nil)".

[r, 2013-06-24 23:37:25]

https://codereview.appspot.com/10478048/diff/1/src/pkg/hash/hash.go
File src/pkg/hash/hash.go (right):

https://codereview.appspot.com/10478048/diff/1/src/pkg/hash/hash.go#newcode13
src/pkg/hash/hash.go:13: // (It is declared here by embedding the io.Writer
interface.)
On 2013/06/24 23:32:47, bradfitz wrote:
> We're now teaching people how Go works in the standard library API docs?

I find the standard format "Writes does this" followed by something not called
Write to be jarring. I could rephrase or drop this, but it feels like pedantry
overriding quality.

[r, 2013-06-24 23:37:25]

Hello golang-dev@googlegroups.com, bradfitz@golang.org (cc:
golang-dev@googlegroups.com),

Please take another look.

[r, 2013-06-24 23:40:32]

Hello golang-dev@googlegroups.com, bradfitz@golang.org (cc:
golang-dev@googlegroups.com),

Please take another look.

[bradfitz, 2013-06-24 23:52:12]

LGTM

[r, 2013-06-24 23:53:17]

*** Submitted as https://code.google.com/p/go/source/detail?r=f6de76ff41a3 ***

hash: tweak the package docs
No semantic change.
I found the wording distracting in a couple of instances and was moved to
improve it.

R=golang-dev, bradfitz
CC=golang-dev
https://codereview.appspot.com/10478048