[golang-dev] code review 9687046: nacl: regularize documentation of box and secretbox. (issue 9687046)

Reviewers: golang-dev1,

Message:
Hello [email protected],

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


Description:
nacl: regularize documentation of box and secretbox.

Please review this at https://codereview.appspot.com/9687046/

Affected files:
    M nacl/box/box.go
    M nacl/secretbox/secretbox.go


Index: nacl/box/box.go
===================================================================
--- a/nacl/box/box.go
+++ b/nacl/box/box.go
@@ -3,10 +3,10 @@
   // license that can be found in the LICENSE file.

   /*
-Package box authenticates and encrypts messages using public-key
cryptography.
+Package box encrypts and authenticates small messages.

   Box uses Curve25519, XSalsa20 and Poly1305 to encrypt and authenticate
-messages. The length of messages is not hidden.
+messages using public-key cryptography. The length of messages is not
hidden.

   It is the caller's responsibility to ensure the uniqueness of nonces—for
   example, by using nonce 1 for the first message, nonce 2 for the second
@@ -55,8 +55,9 @@
   }

   // Seal appends an encrypted and authenticated copy of message to out,
which
-// will be Overhead bytes longer than the original and must not overlap.
The
-// nonce must be unique for each distinct message for a given pair of keys.
+// must not overlap message, and returns the new part of out. The nonce
must be
+// unique for each distinct message for a given pair of keys. The output
will be
+// Overhead bytes longer than the original.
   func Seal(out, message []byte, nonce *[24]byte, peersPublicKey, privateKey
*[32]byte) []byte {
    var sharedKey [32]byte
    Precompute(&sharedKey, peersPublicKey, privateKey)
@@ -70,8 +71,8 @@
   }

   // Open authenticates and decrypts a box produced by Seal and appends the
-// message to out, which must not overlap box. The output will be Overhead
-// bytes smaller than box.
+// message to out, which must not overlap box. It returns the new part of
out.
+// The output will be Overhead bytes smaller than box.
   func Open(out, box []byte, nonce *[24]byte, peersPublicKey, privateKey
*[32]byte) ([]byte, bool) {
    var sharedKey [32]byte
    Precompute(&sharedKey, peersPublicKey, privateKey)
Index: nacl/secretbox/secretbox.go
===================================================================
--- a/nacl/secretbox/secretbox.go
+++ b/nacl/secretbox/secretbox.go
@@ -5,8 +5,8 @@
   /*
   Package secretbox encrypts and authenticates small messages.

-Secretbox uses XSalsa20 and Poly1305 to encrypt and authenticate messages
with
-secret-key cryptography. The length of messages is not hidden.
+Secretbox uses XSalsa20 and Poly1305 to encrypt and authenticate messages
+with secret-key cryptography. The length of messages is not hidden.

   It is the caller's responsibility to ensure the uniqueness of nonces—for
   example, by using nonce 1 for the first message, nonce 2 for the second
@@ -37,9 +37,10 @@
    copy(counter[:], nonce[16:])
   }

-// Seal appends an encrypted and authenticated copy of message to out,
which
-// must not overlap message. The key and nonce pair must be unique for each
-// distinct message and the output will be Overhead bytes longer than
message.
+// Seal appends an encrypted and authenticated copy of message to out,
+// which must not overlap message, and returns the new part of out.
+// The key and nonce pair must be unique for each distinct message and
+// the output will be Overhead bytes longer than message.
   func Seal(out, message []byte, nonce *[24]byte, key *[32]byte) []byte {
    var subKey [32]byte
    var counter [16]byte
@@ -94,8 +95,8 @@
   }

   // Open authenticates and decrypts a box produced by Seal and appends the
-// message to out, which must not overlap box. The output will be Overhead
-// bytes smaller than box.
+// message to out, which must not overlap box. It returns the new part of
out.
+// The output will be Overhead bytes smaller than box.
   func Open(out []byte, box []byte, nonce *[24]byte, key *[32]byte) ([]byte,
bool) {
    if len(box) < Overhead {
     return nil, false