Add docs for Injuries/InjuriesDetail.

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

diff --git a/src/TSN/XML/Injuries.hs b/src/TSN/XML/Injuries.hs
index 8002799c62e0e26f4bb7217740ac4651aaa0235f..f7eba8d7a072796c08aca39a1dab9a76d3a3c586 100644 (file)
--- a/src/TSN/XML/Injuries.hs
+++ b/src/TSN/XML/Injuries.hs
@@ -10,16 +10,19 @@
 --   contains a root element \<message\> that in turn contains zero or
 --   more \<listing\>s.
 --
---   The listings will be mapped to a database table called "injuries"
---   automatically. The root message is not retained.
+--   The listings will be mapped to a database table called
+--   \"injuries_listings\" automatically. The root message is not
+--   retained.
 --
 module TSN.XML.Injuries (
-  injuries_tests,
   pickle_message,
+  -- * Tests
+  injuries_tests,
   -- * WARNING: these are private but exported to silence warnings
   ListingConstructor(..) )
 where
 
+-- System imports.
 import Data.Data ( Data )
 import Data.Typeable ( Typeable )
 import Database.Groundhog (
@@ -45,17 +48,23 @@ import Text.XML.HXT.Core (
   xpText,
   xpWrap )
 
-
+-- Local imports.
 import TSN.DbImport ( DbImport(..), ImportResult(..), run_dbmigrate )
 import TSN.XmlImport ( XmlImport(..) )
 import Xml ( FromXml(..), pickle_unpickle, unpickleable )
 
+-- | XML/Database representation of a team as they appear in the
+--   injuries documents.
+--
 data InjuriesTeam =
   InjuriesTeam {
     team_name :: String,
     team_league :: Maybe String }
   deriving (Data, Eq, Show, Typeable)
 
+
+-- | XML/Database representation of the injury listings.
+--
 data Listing =
   Listing {
     team :: InjuriesTeam,
@@ -64,12 +73,23 @@ data Listing =
     updated :: Maybe Bool }
   deriving (Eq, Show)
 
+
 instance FromXml Listing where
+  -- | The DB analogue of a 'Listing' is... itself!
   type Db Listing = Listing
+
+  -- | To convert between a 'Listing' and a 'Listing', we do nothing.
   from_xml = id
 
+-- | This lets us call 'insert_xml' on a 'Listing' without having to
+--   explicitly convert it to its database analogue first.
+--
 instance XmlImport Listing
 
+
+-- | XML representation of an injuriesxml \<message\>. This is only
+--   used for (un)pickling; 'Message's are not saved to the database.
+--
 data Message =
   Message {
     xml_file_id :: Int,
@@ -77,10 +97,13 @@ data Message =
     category :: String,
     sport :: String,
     listings :: [Listing],
-    time_stamp :: String }
+    time_stamp :: String -- ^ Slightly lax, but we don't save it, so who cares.
+  }
   deriving (Eq, Show)
 
 instance DbImport Message where
+  -- | We import a 'Message' by inserting all of its 'listings'.
+  --
   dbimport msg = mapM_ insert_xml (listings msg) >> return ImportSucceeded
 
   dbmigrate _ = run_dbmigrate $ migrate (undefined :: Listing)
@@ -102,6 +125,8 @@ mkPersist defaultCodegenConfig [groundhog|
 |]
 
 
+-- | A pickler for 'InjuriesTeam's that can convert them to/from XML.
+--
 pickle_injuries_team :: PU InjuriesTeam
 pickle_injuries_team =
   xpElem "team" $
@@ -112,6 +137,8 @@ pickle_injuries_team =
     to_tuple m = (team_name m, team_league m)
 
 
+-- | A pickler for 'Listings's that can convert them to/from XML.
+--
 pickle_listing :: PU Listing
 pickle_listing =
   xpElem "listing" $
@@ -125,6 +152,8 @@ pickle_listing =
     to_tuple l = (team l, teamno l, injuries l, updated l)
 
 
+-- | A pickler for 'Message's that can convert them to/from XML.
+--
 pickle_message :: PU Message
 pickle_message =
   xpElem "message" $
@@ -145,8 +174,12 @@ pickle_message =
                   time_stamp m)
 
 
+--
+-- Tasty Tests
+--
 
--- * Tasty Tests
+-- | A list of all tests for this module.
+--
 injuries_tests :: TestTree
 injuries_tests =
   testGroup
@@ -155,8 +188,10 @@ injuries_tests =
       test_unpickle_succeeds ]
 
 
--- | Warning, succeess of this test does not mean that unpickling
---   succeeded.
+-- | If we unpickle something and then pickle it, we should wind up
+--   with the same thing we started with. WARNING: succeess of this
+--   test does not mean that unpickling succeeded.
+--
 test_pickle_of_unpickle_is_identity :: TestTree
 test_pickle_of_unpickle_is_identity =
   testCase "pickle composed with unpickle is the identity" $ do
@@ -165,6 +200,8 @@ test_pickle_of_unpickle_is_identity =
     actual @?= expected
 
 
+-- | Make sure we can actually unpickle these things.
+--
 test_unpickle_succeeds :: TestTree
 test_unpickle_succeeds =
   testCase "unpickling succeeds" $ do