From 8572ba65c849aa497e0fc3e5b9053e24176c1cd8 Mon Sep 17 00:00:00 2001
From: Didactic Drunk <1479616+didactic-drunk@users.noreply.github.com>
Date: Sat, 14 Sep 2019 04:47:57 -0700
Subject: [PATCH] Documentation.

---
 src/sodium/crypto_box/secret_key.cr | 32 +++++++++++++++++++++++++++--
 src/sodium/secret_box.cr            |  9 ++++----
 2 files changed, 34 insertions(+), 7 deletions(-)

diff --git a/src/sodium/crypto_box/secret_key.cr b/src/sodium/crypto_box/secret_key.cr
index a54b46e..91993de 100644
--- a/src/sodium/crypto_box/secret_key.cr
+++ b/src/sodium/crypto_box/secret_key.cr
@@ -4,7 +4,32 @@ require "./public_key"
 require "../crypto_box"
 
 class Sodium::CryptoBox
-  # Key used for encryption + authentication or encryption without authentication, not for unencrypted signing.
+  # You may either send encrypted signed messages using "Authenticated encryption" or encrypt unsigned messages using "Sealed Boxes".
+  #
+  # For signing without encryption see `Sodium::Sign::SecretKey`.
+  #
+  # # Authenticated encryption
+  # [https://libsodium.gitbook.io/doc/public-key_cryptography/authenticated_encryption](https://libsodium.gitbook.io/doc/public-key_cryptography/authenticated_encryption#purpose)
+  # ```
+  # bob = Sodium::CryptoBox::SecretKey.new
+  # alice = Sodium::CryptoBox::SecretKey.new
+  # message = "hi"
+  #
+  # # Encrypt and sign a message from bob to alice's public_key
+  # bob.box alice.public_key do |box|
+  #   ciphertext = box.encrypt message
+  # end
+  # ```
+  #
+  # # Sealed Boxes
+  # [https://libsodium.gitbook.io/doc/public-key_cryptography/sealed_boxes](https://libsodium.gitbook.io/doc/public-key_cryptography/sealed_boxes#purpose)
+  # ```
+  # secret_key = Sodium::CryptoBox::SecretKey.new
+  # public_key = secret_key.public_key
+  #
+  # ciphertext = public_key.encrypt message
+  # secret_key.decrypt ciphertext
+  # ```
   class SecretKey < Key
     KEY_SIZE  = LibSodium.crypto_box_secretkeybytes.to_i
     SEED_SIZE = LibSodium.crypto_box_seedbytes.to_i
@@ -27,6 +52,7 @@ class Sodium::CryptoBox
     end
 
     # Use existing secret and public keys.
+    #
     # Copies secret key to a SecureBuffer.
     # Recomputes the public key from a secret key if missing.
     def initialize(bytes : Bytes, pkey : Bytes? = nil)
@@ -43,6 +69,7 @@ class Sodium::CryptoBox
     end
 
     # Derive a new secret/public key pair based on a consistent seed.
+    #
     # Copies seed to a SecureBuffer.
     def initialize(*, seed : Bytes, erase = false)
       raise ArgumentError.new("Secret sign seed must be #{SEED_SIZE}, got #{seed.bytesize}") unless seed.bytesize == SEED_SIZE
@@ -87,7 +114,8 @@ class Sodium::CryptoBox
       end
     end
 
-    # Anonymously receive messages without a signatures.
+    # Anonymously receive messages without a signature.
+    #
     # For authenticated messages use `secret_key.box(recipient_public_key).decrypt`.
     def decrypt(src)
       encrypt src.to_slice
diff --git a/src/sodium/secret_box.cr b/src/sodium/secret_box.cr
index 98deb0e..d0ffea0 100644
--- a/src/sodium/secret_box.cr
+++ b/src/sodium/secret_box.cr
@@ -5,15 +5,14 @@ require "./nonce"
 module Sodium
   # [https://libsodium.gitbook.io/doc/secret-key_cryptography](https://libsodium.gitbook.io/doc/secret-key_cryptography)
   #
-  #
   # ```crystal
-  # key = Sodium::SecretBox.new
+  # box = Sodium::SecretBox.new
   # message = "foobar"
-  # encrypted, nonce = key.encrypt message
+  # encrypted, nonce = box.encrypt message
   #
   # # On the other side.
-  # key = Sodium::SecretBox.new key
-  # message = key.decrypt encrypted, nonce
+  # box = Sodium::SecretBox.new key
+  # message = key.decrypt encrypted, nonce: nonce
   # ```
   class SecretBox < Key
     KEY_SIZE   = LibSodium.crypto_secretbox_keybytes.to_i