crypto/cipher: extend the docs of BlockMode and Stream

Change-Id: Iebb5b67c8defec22edd482d587edaf399a7ba82a
Reviewed-on: https://go-review.googlesource.com/37418
Reviewed-by: Adam Langley <agl@golang.org>
Reviewed-by: Ian Lance Taylor <iant@golang.org>

src/crypto/cipher/cipher.go

@@ -29,9 +29,14 @@ type Block interface {
 type Stream interface {
 	// XORKeyStream XORs each byte in the given slice with a byte from the
 	// cipher's key stream. Dst and src may point to the same memory.
+	//
 	// If len(dst) < len(src), XORKeyStream should panic. It is acceptable
 	// to pass a dst bigger than src, and in that case, XORKeyStream will
 	// only update dst[:len(src)] and will not touch the rest of dst.
+	//
+	// Multiple calls to XORKeyStream behave as if the concatenation of
+	// the src buffers was passed in a single run. That is, Stream
+	// maintains state and does not reset at each XORKeyStream call.
 	XORKeyStream(dst, src []byte)
 }
 
@@ -44,6 +49,14 @@ type BlockMode interface {
 	// CryptBlocks encrypts or decrypts a number of blocks. The length of
 	// src must be a multiple of the block size. Dst and src may point to
 	// the same memory.
+	//
+	// If len(dst) < len(src), CryptBlocks should panic. It is acceptable
+	// to pass a dst bigger than src, and in that case, CryptBlocks will
+	// only update dst[:len(src)] and will not touch the rest of dst.
+	//
+	// Multiple calls to CryptBlocks behave as if the concatenation of
+	// the src buffers was passed in a single run. That is, BlockMode
+	// maintains state and does not reset at each CryptBlocks call.
 	CryptBlocks(dst, src []byte)
 }