From 80ed642f8502dc9f5091400a537a7efd25b0bc04 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Olivier=20Ch=C3=A9ron?= <olivier.cheron@gmail.com>
Date: Tue, 22 Aug 2017 20:39:24 +0200
Subject: [PATCH] Add introduction to tutorial

---
 Crypto/Tutorial.hs | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/Crypto/Tutorial.hs b/Crypto/Tutorial.hs
index 2e74fac..158fcc7 100644
--- a/Crypto/Tutorial.hs
+++ b/Crypto/Tutorial.hs
@@ -1,9 +1,31 @@
 -- | Examples of how to use @cryptonite@.
 module Crypto.Tutorial
-    ( -- * Symmetric block ciphers
+    ( -- * API design
+      -- $api_design
+
+      -- * Symmetric block ciphers
       -- $symmetric_block_ciphers
     ) where
 
+-- $api_design
+--
+-- APIs in cryptonite are often based on type classes from package
+-- <https://hackage.haskell.org/package/memory memory>, notably
+-- 'Data.ByteArray.ByteArrayAccess' and 'Data.ByteArray.ByteArray'.
+-- Module "Data.ByteArray" provides many primitives that are useful to
+-- work with cryptonite types.  For example function 'Data.ByteArray.convert'
+-- can transform one 'Data.ByteArray.ByteArrayAccess' concrete type like
+-- 'Crypto.Hash.Digest' to a 'Data.ByteString.ByteString'.
+--
+-- Algorithms and functions needing random bytes are based on type class
+-- 'Crypto.Random.Types.MonadRandom'.  Implementation 'IO' uses a system source
+-- of entropy.  It is also possible to use a 'Crypto.Random.Types.DRG' with
+-- 'Crypto.Random.Types.MonadPseudoRandom'
+--
+-- Error conditions are returned with data type 'Crypto.Error.CryptoFailable'.
+-- Functions in module "Crypto.Error" can convert those values to runtime
+-- exceptions, 'Maybe' or 'Either' values.
+
 -- $symmetric_block_ciphers
 --
 -- > {-# LANGUAGE OverloadedStrings #-}