Add Documentation.

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
 

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")

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:

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?

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)

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,18 +38,22 @@ 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}")
       end
       @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,13 +64,17 @@ 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
       dst = Bytes.new dst_size
       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}")

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:

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?