From 31c3ead8518009e40d3929202e39f0e7a909b4ca Mon Sep 17 00:00:00 2001
From: Didactic Drunk <1479616+didactic-drunk@users.noreply.github.com>
Date: Tue, 6 Aug 2019 04:09:08 -0700
Subject: [PATCH] Add Documentation.

---
 benchmarks/crypto_box.cr            |  6 +++---
 src/sodium/crypto_box.cr            | 11 ++++++++++-
 src/sodium/crypto_box/public_key.cr |  1 +
 src/sodium/crypto_box/secret_key.cr |  1 +
 src/sodium/lib_sodium.cr            |  2 ++
 src/sodium/secret_box.cr            | 11 ++++++++++-
 src/sodium/sign/public_key.cr       |  1 +
 src/sodium/sign/secret_key.cr       |  1 +
 8 files changed, 29 insertions(+), 5 deletions(-)

diff --git a/benchmarks/crypto_box.cr b/benchmarks/crypto_box.cr
index 8b3c2a9..008c5ec 100644
--- a/benchmarks/crypto_box.cr
+++ b/benchmarks/crypto_box.cr
@@ -14,17 +14,17 @@ ebufs1 = sizes.map { |size| Bytes.new(size + Sodium::CryptoBox::MAC_SIZE) }.to_a
 dbufs2 = sizes.map { |size| Bytes.new(size) }.to_a
 ebufs2 = sizes.map { |size| Bytes.new(size + Sodium::CryptoBox::PublicKey::SEAL_SIZE) }.to_a
 
-Benchmark.ips do |bm|
+Benchmark.ips warmup: 0.5 do |bm|
   sizes.each_with_index do |size, i|
     dbuf = dbufs1[i]
     ebuf = ebufs1[i]
 
     bm.report "box encrypt #{size}" do
-      to_alice.encrypt_easy dbuf, ebuf, nonce: nonce
+      to_alice.encrypt dbuf, ebuf, nonce: nonce
     end
 
     bm.report "box decrypt #{size}" do
-      from_bob.decrypt_easy ebuf, dbuf, nonce: nonce
+      from_bob.decrypt ebuf, dbuf, nonce: nonce
     end
   end
 
diff --git a/src/sodium/crypto_box.cr b/src/sodium/crypto_box.cr
index b7216f1..a78dd6f 100644
--- a/src/sodium/crypto_box.cr
+++ b/src/sodium/crypto_box.cr
@@ -17,21 +17,30 @@ module Sodium
       # TODO: precompute using crypto_box_beforenm
     end
 
+    # Encrypts data and returns {ciphertext, nonce}
     def encrypt(src)
       encrypt src.to_slice
     end
 
-    def encrypt(src : Bytes, dst = Bytes.new(src.bytesize + MAC_SIZE), nonce = Nonce.new)
+    # Encrypts data and returns {ciphertext, nonce}
+    #
+    # Optionally supply a destination buffer.
+    def encrypt(src : Bytes, dst = Bytes.new(src.bytesize + MAC_SIZE), nonce = Nonce.new) : {Bytes, Nonce}
       if LibSodium.crypto_box_easy(dst, src, src.bytesize, nonce.to_slice, @public_key.to_slice, @secret_key.to_slice) != 0
         raise Error.new("crypto_box_easy")
       end
       {dst, nonce}
     end
 
+    # Returns decrypted message.
+    #
     def decrypt(src)
       decrypt src.to_slice
     end
 
+    # Returns decrypted message.
+    #
+    # Optionally supply a destination buffer.
     def decrypt(src : Bytes, dst = Bytes.new(src.bytesize - MAC_SIZE), nonce = Nonce.new) : Bytes
       if LibSodium.crypto_box_open_easy(dst, src, src.bytesize, nonce.to_slice, @public_key.to_slice, @secret_key.to_slice) != 0
         raise Error::DecryptionFailed.new("crypto_box_open_easy")
diff --git a/src/sodium/crypto_box/public_key.cr b/src/sodium/crypto_box/public_key.cr
index 22fab3b..9029a67 100644
--- a/src/sodium/crypto_box/public_key.cr
+++ b/src/sodium/crypto_box/public_key.cr
@@ -6,6 +6,7 @@ class Sodium::CryptoBox
     KEY_SIZE  = LibSodium.crypto_box_publickeybytes.to_i
     SEAL_SIZE = LibSodium.crypto_box_sealbytes
 
+    # Returns key
     delegate to_slice, to: @bytes
 
     # :nodoc:
diff --git a/src/sodium/crypto_box/secret_key.cr b/src/sodium/crypto_box/secret_key.cr
index 9c6b00f..21c059d 100644
--- a/src/sodium/crypto_box/secret_key.cr
+++ b/src/sodium/crypto_box/secret_key.cr
@@ -14,6 +14,7 @@ class Sodium::CryptoBox
 
     getter public_key : PublicKey
 
+    # Returns key
     delegate to_slice, to: @sbuf
 
     @seed : SecureBuffer?
diff --git a/src/sodium/lib_sodium.cr b/src/sodium/lib_sodium.cr
index daf6a80..887622d 100644
--- a/src/sodium/lib_sodium.cr
+++ b/src/sodium/lib_sodium.cr
@@ -283,6 +283,7 @@ module Sodium
 end
 
 module Sodium
+  # Constant time memory compare.
   def self.memcmp(a : Bytes, b : Bytes) : Bool
     if a.bytesize != b.bytesize
       false
@@ -293,6 +294,7 @@ module Sodium
     end
   end
 
+  # Constant time memory compare.
   # Raises unless comparison succeeds.
   def self.memcmp!(a, b)
     raise Error::MemcmpFailed.new unless memcmp(a, b)
diff --git a/src/sodium/secret_box.cr b/src/sodium/secret_box.cr
index e18f7e5..b91dd2f 100644
--- a/src/sodium/secret_box.cr
+++ b/src/sodium/secret_box.cr
@@ -20,6 +20,7 @@ module Sodium
     NONCE_SIZE = LibSodium.crypto_secretbox_noncebytes.to_i
     MAC_SIZE   = LibSodium.crypto_secretbox_macbytes.to_i
 
+    # Returns key
     delegate to_slice, to: @buf
 
     # Generate a new random key held in a SecureBuffer.
@@ -37,7 +38,7 @@ module Sodium
 
     # Copy bytes to a new SecureBuffer
     #
-    # Optionally erases bytes after copying if erase is set
+    # Optionally erases bytes after copying if erase is set.
     def initialize(bytes : Bytes, erase = false)
       if bytes.bytesize != KEY_SIZE
         raise ArgumentError.new("Secret key must be #{KEY_SIZE} bytes, got #{bytes.bytesize}")
@@ -45,10 +46,14 @@ module Sodium
       @buf = SecureBuffer.new bytes, erase: erase
     end
 
+    # Encrypts data and returns {ciphertext, nonce}
     def encrypt(data)
       encrypt data.to_slice
     end
 
+    # Encrypts data and returns {ciphertext, nonce}
+    #
+    # Optionally supply a destination buffer.
     def encrypt(src : Bytes, dst : Bytes = Bytes.new(src.bytesize + MAC_SIZE), nonce : Nonce = Nonce.new) : {Bytes, Nonce}
       if dst.bytesize != (src.bytesize + MAC_SIZE)
         raise ArgumentError.new("dst.bytesize must be src.bytesize + MAC_SIZE, got #{dst.bytesize}")
@@ -59,6 +64,7 @@ module Sodium
       {dst, nonce}
     end
 
+    # Returns decrypted message.
     def decrypt(src : Bytes, nonce : Nonce) : Bytes
       dst_size = src.bytesize - MAC_SIZE
       raise Sodium::Error::DecryptionFailed.new("encrypted data too small #{src.bytesize}") if dst_size <= 0
@@ -66,6 +72,9 @@ module Sodium
       decrypt(src, dst, nonce)
     end
 
+    # Returns decrypted message.
+    #
+    # Optionally supply a destination buffer.
     def decrypt(src : Bytes, dst : Bytes, nonce : Nonce) : Bytes
       if dst.bytesize != (src.bytesize - MAC_SIZE)
         raise ArgumentError.new("dst.bytesize must be src.bytesize - MAC_SIZE, got #{dst.bytesize}")
diff --git a/src/sodium/sign/public_key.cr b/src/sodium/sign/public_key.cr
index d4113bd..a0dc20f 100644
--- a/src/sodium/sign/public_key.cr
+++ b/src/sodium/sign/public_key.cr
@@ -5,6 +5,7 @@ module Sodium
     KEY_SIZE = LibSodium.crypto_sign_publickeybytes.to_i
     SIG_SIZE = LibSodium.crypto_sign_bytes.to_i
 
+    # Returns key
     delegate to_slice, to: @bytes
 
     # :nodoc:
diff --git a/src/sodium/sign/secret_key.cr b/src/sodium/sign/secret_key.cr
index 465552d..7b85451 100644
--- a/src/sodium/sign/secret_key.cr
+++ b/src/sodium/sign/secret_key.cr
@@ -20,6 +20,7 @@ module Sodium
 
     getter public_key : PublicKey
 
+    # Returns key
     delegate to_slice, to: @sbuf
 
     @seed : SecureBuffer?