From 98ece426d9296a432766ea106c9fdb7b1bcb715d Mon Sep 17 00:00:00 2001
From: Henning Guenther <h.guenther@tu-bs.de>
Date: Fri, 28 Aug 2009 15:31:46 -0700
Subject: [PATCH] Document Encoding base classes

Ignore-this: 6a7f57460edd3a888d5f214c9aa115b

darcs-hash:20090828223146-a4fee-0e54f4127ceef0ddc6bfd938813b030d5b2faf19
---
 Data/Encoding/Base.hs | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/Data/Encoding/Base.hs b/Data/Encoding/Base.hs
index 20d6400..2fea32a 100644
--- a/Data/Encoding/Base.hs
+++ b/Data/Encoding/Base.hs
@@ -12,15 +12,27 @@ import Data.Word
 import Data.Char
 import Data.Typeable
 
+{- | The base class for all encodings. At least decodeChar, encodeChar and encodeable must be implemented.
+ -}
 class Encoding enc where
+    -- | Read a single character of a ByteSource
     decodeChar :: ByteSource m => enc -> m Char
+    -- | Encode a single character and write it to a ByteSink
     encodeChar :: ByteSink m => enc -> Char -> m ()
+    -- | Read characters from a ByteSource until it is empty
     decode :: ByteSource m => enc -> m String
     decode e = untilM sourceEmpty (decodeChar e)
+    -- | Encode a String and write it to a ByteSink
     encode :: ByteSink m => enc -> String -> m ()
     encode e = mapM_ (encodeChar e)
+    -- | Tests whether a given character is representable in the Encoding.
+    --   If this yields True, encodeChar must not fail.
+    --   If it yields False, encodeChar _must_ throw an exception.
     encodeable :: enc -> Char -> Bool
 
+{- | Wraps all possible encoding types into one data type.
+     Used when a function needs to return an encoding.
+ -}
 data DynEncoding = forall enc. (Encoding enc,Eq enc,Typeable enc,Show enc) => DynEncoding enc
 
 instance Show DynEncoding where