Update (or add) a bunch of documentation.

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

diff --git a/src/TSN/XML/News.hs b/src/TSN/XML/News.hs
index a630ef7025cd6bbb31a4eb3a2db13253ad93687b..7d8ef754a0081a16679200b4c2c4fd2869f28d21 100644 (file)
--- a/src/TSN/XML/News.hs
+++ b/src/TSN/XML/News.hs
@@ -11,8 +11,9 @@
 --   root element \<message\> that contains an entire news item.
 --
 module TSN.XML.News (
-  news_tests,
   pickle_message,
+  -- * Tests
+  news_tests,
   -- * WARNING: these are private but exported to silence warnings
   News_NewsLocationConstructor(..),
   News_NewsTeamConstructor(..),
@@ -80,7 +81,9 @@ instance XmlImport NewsTeam
 
 
 -- | Mapping between News records and NewsTeam records in the
---   database.
+--   database. We don't name the fields because we don't use the names
+--   explicitly; that means we have to give them nice database names
+--   via groundhog.
 --
 data News_NewsTeam = News_NewsTeam
                        (DefaultKey News)
@@ -111,7 +114,9 @@ instance XmlImport NewsLocation
 
 
 -- | Mapping between News records and NewsLocation records in the
---   database.
+--   database. We don't name the fields because we don't use the names
+--   explicitly; that means we have to give them nice database names
+--   via groundhog.
 --
 data News_NewsLocation = News_NewsLocation
                            (DefaultKey News)
@@ -273,9 +278,9 @@ mkPersist tsn_codegen_config [groundhog|
   constructors:
     - name: News_NewsTeam
       fields:
-        - name: news_NewsTeam0
+        - name: news_NewsTeam0 # Default created by mkNormalFieldName
           dbName: news_id
-        - name: news_NewsTeam1
+        - name: news_NewsTeam1 # Default created by mkNormalFieldName
           dbName: news_teams_id
 
 - entity: News_NewsLocation
@@ -283,9 +288,9 @@ mkPersist tsn_codegen_config [groundhog|
   constructors:
     - name: News_NewsLocation
       fields:
-        - name: news_NewsLocation0
+        - name: news_NewsLocation0 # Default created by mkNormalFieldName
           dbName: news_id
-        - name: news_NewsLocation1
+        - name: news_NewsLocation1 # Default created by mkNormalFieldName
           dbName: news_locations_id
 |]
 
@@ -383,8 +388,12 @@ pickle_message =
         to_string = join "\n"
 
 
+--
+-- Tasty Tests
+--
 
--- * Tasty Tests
+-- | A list of all tests for this module.
+--
 news_tests :: TestTree
 news_tests =
   testGroup
@@ -394,6 +403,8 @@ news_tests =
       test_unpickle_succeeds ]
 
 
+-- | Make sure our codegen is producing the correct database names.
+--
 test_news_fields_have_correct_names :: TestTree
 test_news_fields_have_correct_names =
   testCase "news fields get correct database names" $
@@ -415,8 +426,10 @@ test_news_fields_have_correct_names =
     check (x,y) = (x @?= y)
 
 
--- | 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 = testGroup "pickle-unpickle tests"
   [ check "pickle composed with unpickle is the identity"
@@ -430,6 +443,8 @@ test_pickle_of_unpickle_is_identity = testGroup "pickle-unpickle tests"
       actual @?= expected
 
 
+-- | Make sure we can actually unpickle these things.
+--
 test_unpickle_succeeds :: TestTree
 test_unpickle_succeeds = testGroup "unpickle tests"
   [ check "unpickling succeeds"