1 files changed, 22 insertions, 8 deletions
diff --git a/shard/lib/keys.ex b/shard/lib/keys.ex
index 412baa2..3a97b5f 100644
--- a/shard/lib/keys.ex
+++ b/shard/lib/keys.ex
@@ -1,6 +1,6 @@
 defmodule Shard.Keys do
   @moduledoc"""
-    Module for saving private keys.
+  Module for saving private keys, signing messages and checking message signatures.
   """
 
   use Agent
@@ -39,6 +39,10 @@ defmodule Shard.Keys do
     :binary.longest_common_suffix([pk, suffix]) == byte_size(suffix)
   end
 
+  @doc"""
+  Return any public key for which we have the secret key. Generates a new keypair
+  if necessary.
+  """
   def get_any_identity() do
     Agent.get(__MODULE__, fn _ ->
       case list_identities() do
@@ -96,6 +100,9 @@ defmodule Shard.Keys do
     end
   end
 
+  @doc"""
+  Check if we have the secret key associated with a public key.
+  """
   def have_sk?(pk) do
     case :dets.lookup @key_db, pk do
       [{^pk, _sk}] -> true
@@ -103,6 +110,9 @@ defmodule Shard.Keys do
     end
   end
 
+  @doc"""
+  Return the secret key associated with a public key if we have it or `nil` otherwise.
+  """
   def get_sk(pk) do
     case :dets.lookup @key_db, pk do
       [{^pk, sk}] -> sk
@@ -111,12 +121,12 @@ defmodule Shard.Keys do
   end
 
   @doc"""
-    Lookup the secret key for a pk and generate a detached signature for a message.
+  Lookup the secret key for a pk and generate a detached signature for a message.
 
-    The original message is not returned.
+  The original message is not returned.
 
-    Answer is {:ok, signature} if it worked, or :not_found if we didn't find the key.
-    
+  Answer is {:ok, signature} if it worked, or :not_found if we don't have the corresponding
+  secret key.
   """
   def sign_detached(pk, bin) do
     case :dets.lookup @key_db, pk do
@@ -127,9 +137,9 @@ defmodule Shard.Keys do
   end
 
   @doc"""
-    Verify a detached signature for a message
+  Verify a detached signature for a message
 
-    Returns :ok if the signature was correct.
+  Returns :ok if the signature was correct.
   """
   def verify(pk, bin, sign) do
     if valid_identity_pk? pk do
@@ -143,12 +153,16 @@ defmodule Shard.Keys do
   end
 
   @doc"""
-    Check if a public key is a valid identity pk. Requirement: have the correct suffix.
+  Check if a public key is a valid identity pk. Requirement: have the correct suffix.
   """
   def valid_identity_pk?(pk) do
     check_suffix(pk, Application.get_env(:shard, :identity_suffix))
   end
 
+  @doc"""
+  Creates a displayable representation of a public key by taking the hex representation
+  of its first four bytes. (not tamper proof but better than nothing)
+  """
   def pk_display(pk) do
     pk
     |> binary_part(0, 4)