From a7ae66b37e8714b8f8fb3f7749c867058e9f2021 Mon Sep 17 00:00:00 2001 From: Michael Orlitzky Date: Tue, 21 Jan 2014 16:26:47 -0500 Subject: [PATCH] Fix some docs in Odds and Weather. --- src/TSN/XML/Odds.hs | 59 ++++++++++++++++++++++-------------------- src/TSN/XML/Weather.hs | 33 ++++++++++++++++++----- 2 files changed, 57 insertions(+), 35 deletions(-) diff --git a/src/TSN/XML/Odds.hs b/src/TSN/XML/Odds.hs index bab8c28..3fd2906 100644 --- a/src/TSN/XML/Odds.hs +++ b/src/TSN/XML/Odds.hs @@ -7,9 +7,9 @@ {-# LANGUAGE TemplateHaskell #-} {-# LANGUAGE TypeFamilies #-} --- | Parse TSN XML for the DTD "Odds_XML.dtd". Each document contains --- a root element \ that contains a bunch of other --- unorganized crap. +-- | Parse TSN XML for the DTD \"Odds_XML.dtd\". Each document +-- contains a root element \ that contains a bunch of +-- other... disorganized... information. -- module TSN.XML.Odds ( pickle_message, @@ -78,10 +78,10 @@ import Xml ( -- | The casinos should have their own table, but the lines don't --- belong in that table (there should be another table joining the --- casinos and the thing the lines are for together.) +-- belong in that table (there is a separate table for +-- 'OddsGameLine' which associates the two). -- --- We drop the 'Game' prefix because the Casinos really aren't +-- We drop the \"Game\" prefix because the casinos really aren't -- children of the games; the XML just makes it seem that way. -- data OddsCasino = @@ -121,14 +121,16 @@ instance ToDb OddsGameCasinoXml where instance FromXml OddsGameCasinoXml where -- | We convert from XML to the database by dropping the line field. + -- from_xml OddsGameCasinoXml{..} = OddsCasino { casino_client_id = xml_casino_client_id, casino_name = xml_casino_name } --- | This allows us to call 'insert_xml' on an 'OddsGameCasinoXml' --- without first converting it to the database representation. +-- | This allows us to insert the XML representation 'OddsGameCasinoXml' +-- directly. +-- instance XmlImport OddsGameCasinoXml @@ -188,9 +190,8 @@ instance FromXml OddsGameHomeTeamXml where db_abbr = xml_home_abbr, db_team_name = xml_home_team_name } --- | XmlImport allows us to call 'insert_xml' directly on an --- 'OddsGameHomeTeamXml' without explicitly converting it to the --- associated database type. +-- | This allows us to insert the XML representation +-- 'OddsGameHomeTeamXml' directly. -- instance XmlImport OddsGameHomeTeamXml where @@ -229,9 +230,8 @@ instance FromXml OddsGameAwayTeamXml where xml_away_abbr xml_away_team_name --- | XmlImport allows us to call 'insert_xml' directly on an --- 'OddsGameAwayTeamXml' without explicitly converting it to the --- associated database type. +-- | This allows us to insert the XML representation +-- 'OddsGameAwayTeamXml' directly. -- instance XmlImport OddsGameAwayTeamXml where @@ -239,6 +239,7 @@ instance XmlImport OddsGameAwayTeamXml where -- * OddsGame_OddsGameTeam -- | Database mapping between games and their home/away teams. +-- data OddsGame_OddsGameTeam = OddsGame_OddsGameTeam { ogogt_odds_games_id :: DefaultKey OddsGame, @@ -260,7 +261,7 @@ newtype OddsGameOverUnderXml = -- | This database representation of the casino lines can't be -- constructed from the one in the XML. The casinos within --- Game>HomeTeam, Game>AwayTeam, and Game>Over_Under are all more or +-- Game-\>HomeTeam, Game-\>AwayTeam, and Game-\>Over_Under are all more or -- less the same. We don't need a bajillion different tables to -- store that, just one tying the casino/game pair to the three -- lines. @@ -293,7 +294,7 @@ data OddsGame = db_game_home_team_rotation_number :: Int } --- | XML representation of a game. +-- | XML representation of an 'OddsGame'. -- data OddsGameXml = OddsGameXml { @@ -319,6 +320,9 @@ instance ToDb OddsGameXml where type Db OddsGameXml = OddsGame instance FromXmlFk OddsGameXml where + -- | Each 'OddsGameXml' is contained in an 'Odds'. In other words + -- the foreign key for 'OddsGame' points to an 'Odds'. + -- type Parent OddsGameXml = Odds -- | To convert from the XML representation to the database one, we @@ -340,8 +344,7 @@ instance FromXmlFk OddsGameXml where db_game_home_team_rotation_number = (xml_home_rotation_number xml_game_home_team) } --- | This lets us call 'insert_xml_fk' directly on an 'OddsGameXml' --- without converting it to the database representation explicitly. +-- | This lets us insert the XML representation 'OddsGameXml' directly. -- instance XmlImportFk OddsGameXml @@ -350,16 +353,16 @@ instance XmlImportFk OddsGameXml -- | This is our best guess at what occurs in the Odds_XML -- documents. It looks like each consecutive set of games can --- optionally have some notes appear before it. Each "note" comes as --- its own ... element. +-- optionally have some notes appear before it. Each \"note\" comes +-- as its own \...\ element. -- -- The notes are ignored completely in the database; we only bother -- with them to ensure that we're (un)pickling correctly. -- --- We can't group the notes with a "set" of 'OddsGame's, because that --- leads to ambiguity in parsing. Since we're going to ignore the --- notes anyway, we just stick them with an arbitrary game. C'est la --- vie. +-- We can't group the notes with a \"set\" of 'OddsGame's, because +-- that leads to ambiguity in parsing. Since we're going to ignore +-- the notes anyway, we just stick them with an arbitrary +-- game. C'est la vie. -- data OddsGameWithNotes = OddsGameWithNotes { @@ -370,8 +373,8 @@ data OddsGameWithNotes = -- * Odds/Message --- | Database and representation of the top-level Odds object (a --- 'Message'). +-- | Database representation of a 'Message'. +-- data Odds = Odds { db_xml_file_id :: Int, @@ -385,6 +388,7 @@ data Odds = -- | The XML representation of 'Odds'. +-- data Message = Message { xml_xml_file_id :: Int, @@ -421,8 +425,7 @@ instance FromXml Message where db_line_time = xml_line_time, db_time_stamp = xml_time_stamp } --- | This lets us call 'insert_xml' on a Message directly, without --- having to convert it to its database representation explicitly. +-- | This lets us insert the XML representation 'Message' directly. -- instance XmlImport Message diff --git a/src/TSN/XML/Weather.hs b/src/TSN/XML/Weather.hs index 3279ec8..ae79a44 100644 --- a/src/TSN/XML/Weather.hs +++ b/src/TSN/XML/Weather.hs @@ -5,7 +5,7 @@ {-# LANGUAGE TemplateHaskell #-} {-# LANGUAGE TypeFamilies #-} --- | Parse TSN XML for the DTD "weatherxml.dtd". Each document +-- | Parse TSN XML for the DTD \"weatherxml.dtd\". Each document -- contains a bunch of forecasts, which each contain one league, and -- that league contains a bunch of listings. -- @@ -60,6 +60,8 @@ import Xml ( -- DB/XML Data types -- +-- * WeatherForecastListing/WeatherForecastListingXml + -- | XML representation of a weather forecast listing. -- data WeatherForecastListingXml = @@ -83,10 +85,13 @@ data WeatherForecastListing = instance ToDb WeatherForecastListingXml where type Db WeatherForecastListingXml = WeatherForecastListing --- | This is needed to define the XmlImport instance for --- 'WeatherForecastListing'. +-- | This is needed to define the 'XmlImportFk' instance for +-- 'WeatherForecastListing'. -- instance FromXmlFk WeatherForecastListingXml where + -- | Each 'WeatherForecastListingXml' is contained in a + -- 'WeatherForecast'. + -- type Parent WeatherForecastListingXml = WeatherForecast from_xml_fk fk WeatherForecastListingXml{..} = @@ -95,12 +100,14 @@ instance FromXmlFk WeatherForecastListingXml where db_teams = xml_teams, db_weather = xml_weather } --- | Allows us to call 'insert_xml' on the XML representation of --- WeatherForecastListing. +-- | This allows us to insert the XML representation +-- 'WeatherForecastListingXml' directly. -- instance XmlImportFk WeatherForecastListingXml +-- * WeatherLeague + -- | XML representation of a league, as they appear in the weather -- documents. There is no associated database representation because -- the league element really adds no information besides its own @@ -114,6 +121,9 @@ data WeatherLeague = listings :: [WeatherForecastListingXml] } deriving (Eq, Show) + +-- * WeatherForecast/WeatherForecastXml + -- | Database representation of a weather forecast. -- data WeatherForecast = @@ -157,6 +167,8 @@ instance FromXmlFk WeatherForecastXml where instance XmlImportFk WeatherForecastXml +-- * Weather/Message + -- | The database representation of a weather message. -- data Weather = @@ -196,12 +208,16 @@ instance FromXml Message where db_title = xml_title, db_time_stamp = xml_time_stamp } --- | This allows us to call 'insert_xml' on a 'Message' without first --- converting it to the database representation. +-- | This allows us to insert the XML representation 'Message' +-- directly. -- instance XmlImport Message +-- +-- Database stuff +-- + mkPersist tsn_codegen_config [groundhog| - entity: Weather constructors: @@ -255,6 +271,9 @@ instance DbImport Message where return ImportSucceeded +--- +--- Pickling +--- -- | Pickler to convert a 'WeatherForecastListingXml' to/from XML. -- -- 2.43.2