code review 6631044: crypto/cipher: add examples

crypto/cipher: add examples

Fixes issue 1390.

[agl1, 2012-10-08 19:36:23]

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

I'd like you to review this change to
https://go.googlecode.com/hg/

[minux1, 2012-10-08 19:38:12]

https://codereview.appspot.com/6631044/diff/1002/src/pkg/crypto/cipher/exampl...
File src/pkg/crypto/cipher/example_test.go (right):

https://codereview.appspot.com/6631044/diff/1002/src/pkg/crypto/cipher/exampl...
src/pkg/crypto/cipher/example_test.go:16: func ExampleNewCBCDecrypter(key,
ciphertext []byte) ([]byte, error) {
example functions can't take arguments.

[agl1, 2012-10-08 19:42:23]

https://codereview.appspot.com/6631044/diff/1002/src/pkg/crypto/cipher/exampl...
File src/pkg/crypto/cipher/example_test.go (right):

https://codereview.appspot.com/6631044/diff/1002/src/pkg/crypto/cipher/exampl...
src/pkg/crypto/cipher/example_test.go:16: func ExampleNewCBCDecrypter(key,
ciphertext []byte) ([]byte, error) {
On 2012/10/08 19:38:12, minux wrote:
> example functions can't take arguments.

Although the arguments don't appear in the example, I think it's clearer here to
have a free variable called `key', than to fluff around with reading a random
key and distract from the subject of the example.

[adg, 2012-10-12 01:41:55]

https://codereview.appspot.com/6631044/diff/1002/src/pkg/crypto/cipher/exampl...
File src/pkg/crypto/cipher/example_test.go (right):

https://codereview.appspot.com/6631044/diff/1002/src/pkg/crypto/cipher/exampl...
src/pkg/crypto/cipher/example_test.go:16: func ExampleNewCBCDecrypter(key,
ciphertext []byte) ([]byte, error) {
On 2012/10/08 19:42:23, agl1 wrote:
> On 2012/10/08 19:38:12, minux wrote:
> > example functions can't take arguments.
> 
> Although the arguments don't appear in the example, I think it's clearer here
to
> have a free variable called `key', than to fluff around with reading a random
> key and distract from the subject of the example.

If you have actual key, ciphertext, and plaintext globals then you can actually
make these examples executable by including an Output: comment at the end of the
function.

As they are, the user doesn't see the functions signature so the return
statements are a non-sequitur.

[agl2, 2012-10-17 23:21:18]

On 2012/10/12 01:41:55, adg wrote:
> If you have actual key, ciphertext, and plaintext globals then you can
actually
> make these examples executable by including an Output: comment at the end of
the
> function.

Ok. Nobody likes the arguments to example functions it seems.

Have removed that and added // Output comments in the case where it's possible.
(Several the examples generate random outputs. I could make them deterministic,
but at the cost of clarity in the example because you would actually want them
to be random in real life.)

[agl1, 2012-10-31 20:37:46]

*** Submitted as http://code.google.com/p/go/source/detail?r=5f67048f835c ***

crypto/cipher: add examples

Fixes issue 1390.

R=golang-dev, minux.ma, adg, agl
CC=golang-dev
http://codereview.appspot.com/6631044