Update documentation.

[dead/htsn-import.git] / src / TSN / XmlImport.hs

diff --git a/src/TSN/XmlImport.hs b/src/TSN/XmlImport.hs
index 4300e87ff4d6182475fcda1f30071b2082a43030..022ddad0bb381e2976e049b671141c3bcd7642d0 100644 (file)
--- a/src/TSN/XmlImport.hs
+++ b/src/TSN/XmlImport.hs
@@ -1,6 +1,8 @@
 {-# LANGUAGE FlexibleContexts #-}
 {-# LANGUAGE GADTs #-}
 
+-- | Definition of the XmlImport class.
+--
 module TSN.XmlImport (
   XmlImport(..) )
 where
@@ -14,6 +16,20 @@ import Database.Groundhog.Core ( PersistBackend, PersistEntity )
 import Xml ( FromXml(..) )
 
 
+-- | In Groundhog, there is a typeclass of things you can insert into
+--   the database. What we usually have, though, is an XML
+--   representation of something that has a Groundhog analogue that we
+--   could insert into the database. It would be real nice if we could
+--   just insert the XML thing and not have to convert back and
+--   forth. That's what the 'XmlImport' class lets you do.
+--
+--   Moreover, there is a contraint on the class that the type must
+--   also be a member of the 'FromXml' class. This allows us to define
+--   default implementations of \"insert me\" generically. Given any
+--   XML thing that can be converted to a database thing, we just do
+--   the conversion and then insert normally (however Groundhog would
+--   do it).
+--
 class (FromXml a, PersistEntity (Db a)) => XmlImport a where
   -- | This is similar to the signature for Groundhog's 'insert'
   --   function, except the 'AutoKey' we return is for our 'Db'