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>

diff --git a/src/crypto/cipher/cipher.go b/src/crypto/cipher/cipher.go
index 531ecad9ac00febd80a85475b27f4a209e751fa4..0950ea9e80db867ba7f66c38fdf4a2fec1da3cc7 100644 (file)
--- a/src/crypto/cipher/cipher.go
+++ b/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)
 }