add more documentation to types

Web/Campfire.hs

@@ -72,7 +72,7 @@ getRooms = withEnv $ \key sub -> do
   return $ (unRooms . unWrap . readResult) result
 
 -- |Get a specific room by Room ID.
-getRoom :: Integer -- ^ Room ID
+getRoom :: Id -- ^ Room ID
            -> CampfireM Room
 getRoom rid = withEnv $ \key sub -> do
   resp <- doGet key sub pth []
@@ -89,47 +89,47 @@ getPresence = withEnv $ \key sub -> do
   return $ (unRooms . unWrap . readResult) result
 
 -- |Change the topic of a particular room.
-setRoomTopic :: Integer                            -- ^ Room ID
+setRoomTopic :: Id                                 -- ^ Room ID
                 -> T.Text                          -- ^ New topic
                 -> CampfireM (Int, LBS.ByteString) -- ^ Status code and body (may change)
 setRoomTopic rid topic = updateRoom rid RoomUpdate { updateRoomName  = Nothing, 
                                                      updateRoomTopic = Just topic }
 
 -- |Change the name of a particular room.
-setRoomName :: Integer                            -- ^ Room ID
+setRoomName :: Id                                 -- ^ Room ID
                -> T.Text                          -- ^ New room name
                -> CampfireM (Int, LBS.ByteString) -- ^ Status code and body (may change)
 setRoomName rid name = updateRoom rid RoomUpdate { updateRoomName  = Just name, 
                                                    updateRoomTopic = Nothing }
 
-updateRoom :: Integer -> RoomUpdate -> CampfireM (Int, LBS.ByteString)
+updateRoom :: Id -> RoomUpdate -> CampfireM (Int, LBS.ByteString)
 updateRoom rid update = withEnv $ \key sub ->
   doPut key sub pth $ encode update
                   where pth   = T.concat ["room/", i2t rid, ".json"]
 
 -- |Causes the authenticated user to join a particular room.
-joinRoom :: Integer                            -- ^ Room ID
+joinRoom :: Id                                 -- ^ Room ID
             -> CampfireM (Int, LBS.ByteString) -- ^ Status code and body (may change)
 joinRoom rid = withEnv $ \key sub ->
   doPost key sub pth LBS.empty
                   where pth   = T.concat ["room/", i2t rid, "/join.json"]
 
 -- |Causes the authenticated user to leave a particular room.
-leaveRoom :: Integer                            -- ^ Room ID
+leaveRoom :: Id                                 -- ^ Room ID
              -> CampfireM (Int, LBS.ByteString) -- ^ Status code and body (may change)
 leaveRoom rid = withEnv $ \key sub ->
   doPost key sub pth LBS.empty
                   where pth   = T.concat ["room/", i2t rid, "/leave.json"]
 
 -- |Locks a particular room.
-lockRoom :: Integer                            -- ^ Roomd ID
+lockRoom :: Id                                 -- ^ Roomd ID
             -> CampfireM (Int, LBS.ByteString) -- ^ Status code and body (may change)
 lockRoom rid = withEnv $ \key sub ->
   doPost key sub pth LBS.empty
                   where pth   = T.concat ["room/", i2t rid, "/lock.json"]
 
 -- |Unlocks a particular room.
-unlockRoom :: Integer                            -- ^ Room ID
+unlockRoom :: Id                                 -- ^ Room ID
               -> CampfireM (Int, LBS.ByteString) -- ^ Status code and body (may change)
 unlockRoom rid = withEnv $ \key sub ->
   doPost key sub pth LBS.empty
@@ -145,7 +145,7 @@ getMe = withEnv $ \key sub -> do
   return $ (unRootUser . unWrap . readResult) result
 
 -- |Get information about the requested user.
-getUser :: Integer  -- ^ User ID
+getUser :: Id  -- ^ User ID
            -> CampfireM User
 getUser rid = withEnv $ \key sub -> do
   resp <- doGet key sub pth []
@@ -156,29 +156,29 @@ getUser rid = withEnv $ \key sub -> do
 --------- Message Operations
 
 -- |Say something in a room as the currently authenticated user.
-speak :: Integer      -- ^ The room ID in which to speak
+speak :: Id           -- ^ The room ID in which to speak
          -> Statement -- ^ The statement to send to the room
          -> CampfireM (Int, LBS.ByteString) -- ^ Status code and body (may change)
 speak rid stmt = withEnv $ \key sub ->
   doPost key sub pth $ encode stmt
             where pth = T.concat ["room/", i2t rid, "/speak.json"]
 
 -- |Put a star next to a message. That message will then show up in that day's highlights.
-highlightMessage :: Integer                            -- ^ Message ID
+highlightMessage :: Id                                 -- ^ Message ID
                     -> CampfireM (Int, LBS.ByteString) -- ^ Status code and body (may change)
 highlightMessage mid = withEnv $ \key sub ->
   doPost key sub pth LBS.empty
             where pth = T.concat ["messages/", i2t mid, "/star.json"]
 
 -- |Remove the star next to a message.
-unhighlightMessage :: Integer                            -- ^ Message ID
+unhighlightMessage :: Id                                 -- ^ Message ID
                       -> CampfireM (Int, LBS.ByteString) -- ^ Status code and body (may change)
 unhighlightMessage mid = withEnv $ \key sub ->
   doDelete key sub pth LBS.empty
             where pth = T.concat ["messages/", i2t mid, "/star.json"]
 
 -- |Receive a list of recent messages in a particular room.
-getRecentMessages :: Integer          -- ^ Room ID
+getRecentMessages :: Id               -- ^ Room ID
                      -> Maybe Integer -- ^ Optional limit. Default is 100
                      -> Maybe Integer -- ^ Optional message ID. Setting this will retreive messages since that message was received.
                      -> CampfireM [Message]
@@ -194,7 +194,7 @@ getRecentMessages rid limit since_id = withEnv $ \key sub -> do
             limitS (Just i)  = [("since_message_id", Just $ BS.pack $ show i)]
 
 -- |Get a transcript of all messages in a room for the day.
-getTodayTranscript :: Integer -- ^ Room ID
+getTodayTranscript :: Id -- ^ Room ID
                       -> CampfireM [Message]
 getTodayTranscript rid = withEnv $ \key sub -> do
   resp <- doGet key sub pth []
@@ -203,7 +203,7 @@ getTodayTranscript rid = withEnv $ \key sub -> do
       where pth = T.concat ["room/", i2t rid, "/transcript.json"]
 
 -- |Get a transcript of all messages in a room for a particular day
-getTranscript :: Integer -- ^ Room ID
+getTranscript :: Id      -- ^ Room ID
                  -> Day  -- ^ Day from which to retrieve the transcript
                  -> CampfireM [Message]
 getTranscript rid day = withEnv $ \key sub -> do
@@ -217,7 +217,7 @@ getTranscript rid day = withEnv $ \key sub -> do
 --------- Upload Operations
 
 -- |Get a list of up to 5 recent uploads to a given room
-getUploads :: Integer -- ^ Room ID
+getUploads :: Id -- ^ Room ID
               -> CampfireM [Upload]
 getUploads rid = withEnv $ \key sub -> do
   resp <- doGet key sub pth []
@@ -228,8 +228,8 @@ getUploads rid = withEnv $ \key sub -> do
 --FIXME: this may not work, getting 404s
 
 -- |Retrieve a particular upload from a room.
-getUpload :: Integer    -- ^ Room ID
-             -> Integer -- ^ Upload ID
+getUpload :: Id    -- ^ Room ID
+             -> Id -- ^ Upload ID
              -> CampfireM Upload
 getUpload rid uid = withEnv $ \key sub -> do
   resp <- doGet key sub pth []

Web/Campfire/Types.hs

@@ -1,11 +1,39 @@
+--------------------------------------------------------------------
+-- |
+-- Module      : Web.Campfire.Types
+-- Description : Types returned by the Campfire API
+-- Copyright   : (c) Michael Xavier 2011
+-- License     : MIT
+--
+-- Maintainer: Michael Xavier <michael@michaelxavier.net>
+-- Stability : provisional
+-- Portability: portable
+--
+--------------------------------------------------------------------
+
 {-# LANGUAGE DeriveDataTypeable, GeneralizedNewtypeDeriving, OverloadedStrings #-}
-module Web.Campfire.Types where
+module Web.Campfire.Types ( Room(..),
+                            RoomWithRoot(..),
+                            Rooms(..),
+                            RoomUpdate(..),
+                            Message(..),
+                            Messages(..),
+                            MessageType(..),
+                            Statement(..),
+                            Sound(..),
+                            User(..),
+                            UserWithRoot(..),
+                            UserType(..),
+                            Upload(..),
+                            Uploads(..),
+                            UploadWithRoot(..),
+                            Id,
+                            CampfireTime(..) ) where
 
 import Control.Applicative ((<$>), (<*>), pure)
 import Control.Monad (mzero)
 import Data.Aeson
 import qualified Data.Aeson.Types as AT (typeMismatch, Parser)
---import Data.Attoparsec (parse, maybeResult, eitherResult, Parser)
 import qualified Data.Text as T
 import Data.Time.Clock (UTCTime)
 import Data.Time.Format
@@ -15,19 +43,20 @@ import Data.Typeable
 import Locale (defaultTimeLocale)
 
 ---------- Rooms
-data Room = Room { roomId               :: Id, -- I sure don't like this solution
-                   roomName             :: T.Text,
-                   roomTopic            :: Maybe T.Text,
-                   roomMembershipLimit  :: Integer,
-                   roomFull             :: Maybe Bool,
-                   roomOpenToGuests     :: Maybe Bool,
-                   roomActiveTokenValue :: Maybe T.Text,
-                   roomUpdatedAt        :: CampfireTime,
-                   roomCreatedAt        :: CampfireTime,
-                   roomUsers            :: Maybe [User] } deriving (Show)
+data Room 
+  -- |A chat room on a Campfire site
+  = Room { roomId               :: Id,
+           roomName             :: T.Text,
+           roomTopic            :: Maybe T.Text, -- ^ Room topic if available
+           roomMembershipLimit  :: Integer,      -- ^ Maximum number of users that may be in this room
+           roomFull             :: Maybe Bool,   -- ^ May not be present depending on the API call used
+           roomOpenToGuests     :: Maybe Bool,   -- ^ May not be present depending on the API call used
+           roomActiveTokenValue :: Maybe T.Text, -- ^ Campfire API doesn't really specify what this means
+           roomUpdatedAt        :: CampfireTime,
+           roomCreatedAt        :: CampfireTime,
+           roomUsers            :: Maybe [User] } deriving (Eq, Ord, Read, Show, Typeable)
 
  -- There is probably a better way to do this
- --TODO: need to pull the room out of the root object
 instance FromJSON Room where
   parseJSON (Object v) = Room <$> v .:| ("id", 0)
                               <*> v .:  "name"
@@ -41,22 +70,27 @@ instance FromJSON Room where
                               <*> v .:? "users"
   parseJSON _ = mzero
 
-newtype RoomWithRoot = RoomWithRoot { unRootRoom :: Room } deriving (Show)
+-- |Utility type used for extracting a Room from the root JSON object the Campfire API returns
+newtype RoomWithRoot = RoomWithRoot { unRootRoom :: Room } deriving (Eq, Ord, Read, Show, Typeable)
+
 
 instance FromJSON RoomWithRoot where
   parseJSON (Object v) = RoomWithRoot <$> v .: "room"
   parseJSON _          = mzero
 
 
-newtype Rooms = Rooms { unRooms :: [Room] } deriving (Show)
+-- |Utility type used for extracting a Room from the list returned by the Campfire API
+newtype Rooms = Rooms { unRooms :: [Room] } deriving (Eq, Ord, Read, Show, Typeable)
+
 
 instance FromJSON Rooms where
   parseJSON (Object v) = Rooms <$> v .: "rooms"
   parseJSON _          = mzero
 
 
+-- |Modification to be made to a room.
 data RoomUpdate = RoomUpdate { updateRoomName  :: Maybe T.Text, 
-                               updateRoomTopic :: Maybe T.Text } deriving (Show)
+                               updateRoomTopic :: Maybe T.Text } deriving (Eq, Ord, Read, Show, Typeable)
 
 --TODO: maybe omit missing fields
 instance ToJSON RoomUpdate where
@@ -65,12 +99,14 @@ instance ToJSON RoomUpdate where
 
 
 ---------- Messages
+
+-- |A single line of dialog in a particular chat
 data Message = Message { messageId        :: Id,
                          messageBody      :: Maybe T.Text,
                          messageRoomId    :: Id,
                          messageUserId    :: Maybe Id,
                          messageCreatedAt :: CampfireTime,
-                         messageType      :: MessageType } deriving (Show)
+                         messageType      :: MessageType } deriving (Eq, Ord, Read, Show, Typeable)
 
 instance FromJSON Message where
   -- consider using an ADT for type
@@ -82,21 +118,23 @@ instance FromJSON Message where
                                  <*> v .: "type"
   parseJSON _          = mzero
 
-newtype Messages = Messages { unMessages :: [Message] } deriving (Show)
+-- |Utility type used for extracting a Message from the list returned by the Campfire API
+newtype Messages = Messages { unMessages :: [Message] } deriving (Eq, Ord, Read, Show, Typeable)
 
 instance FromJSON Messages where
   parseJSON (Object v) = Messages <$> v .: "messages"
   parseJSON _          = mzero
 
 
+-- |Distinct types of messages which can be found in Campfire
 data MessageType = TextMessage |
-                   PasteMessage |
-                   SoundMessage |
+                   PasteMessage |          -- ^ Monospaced text displayed in block form
+                   SoundMessage |          -- ^ Audio sound effect message
                    AdvertisementMessage |
                    AllowGuestsMessage |
                    DisallowGuestsMessage |
                    IdleMessage |
-                   KickMessage |
+                   KickMessage |           -- ^ Message indicating that a user was kicked out
                    LeaveMessage |
                    SystemMessage |
                    TimestampMessage |
@@ -129,11 +167,11 @@ instance FromJSON MessageType where
   parseJSON _          = mzero
 
 ---------- Statements
--- Statements are messages that you can send to CampFire
+-- |Statements are messages that you can send to CampFire.
 data Statement = TextStatement { statementBody :: T.Text } |
                  PasteStatement { statementBody :: T.Text} |
-                 SoundStatement { soundType :: Sound     } |
-                 TweetStatement { statementUrl  :: T.Text}
+                 SoundStatement { soundType :: Sound     } | -- ^ Play an audio message in the room
+                 TweetStatement { statementUrl  :: T.Text}   -- ^ Display a tweet from a url on Twitter
                  deriving (Eq, Ord, Read, Show, Typeable)
 
 --FIXME: wrap all instances in root object
@@ -151,6 +189,7 @@ instance ToJSON Statement where
 (|-) label obj = object [label .= obj]
 
 
+-- |Different pre-set sounds that can be played in a room.
 data Sound = Rimshot |
              Crickets |
              Trombone
@@ -163,10 +202,12 @@ instance ToJSON Sound where
 
 
 ---------- Users
+
+-- |User which can be found in any number of rooms.
 data User = User { userId           :: Id,
                    userName         :: T.Text,
                    userEmailAddress :: T.Text,
-                   userAdmin        :: Bool,
+                   userAdmin        :: Bool,   -- ^ User has administrative privileges
                    userCreatedAt    :: CampfireTime,
                    userType         :: UserType } 
             deriving (Eq, Ord, Read, Show, Typeable)
@@ -181,12 +222,14 @@ instance FromJSON User where
                               <*> v .: "type"
   parseJSON _          = mzero
 
-newtype UserWithRoot = UserWithRoot { unRootUser :: User } deriving (Show)
+-- |Utility type used for extracting a User from the root JSON object the Campfire API returns
+newtype UserWithRoot = UserWithRoot { unRootUser :: User } deriving (Eq, Ord, Read, Show, Typeable)
 
 instance FromJSON UserWithRoot where
   parseJSON (Object v) = UserWithRoot <$> v .: "user"
   parseJSON _          = mzero
 
+-- |Different classes of users that can be found in chat.
 data UserType = Member | 
                 Guest
                 deriving (Eq, Ord, Read, Show, Typeable)
@@ -199,6 +242,8 @@ instance FromJSON UserType where
   parseJSON _          = mzero
 
 ---------- Uploads
+
+-- |File upload in a room.
 data Upload = Upload { uploadId          :: Id,
                        uploadName        :: T.Text,
                        uploadRoomId      :: Id,
@@ -221,13 +266,15 @@ instance FromJSON Upload  where
                                 <*> v .: "created_at"
   parseJSON _          = mzero
 
-newtype Uploads = Uploads { unUploads :: [Upload] } deriving (Show)
+-- |Utility type used for extracting a Upload from the list returned by the Campfire API
+newtype Uploads = Uploads { unUploads :: [Upload] } deriving (Eq, Ord, Read, Show, Typeable)
 
 instance FromJSON Uploads where
   parseJSON (Object v) = Uploads <$> v .: "uploads"
   parseJSON _          = mzero
 
-newtype UploadWithRoot = UploadWithRoot { unRootUpload :: Upload } deriving (Show)
+-- |Utility type used for extracting an Upload from the root JSON object the Campfire API returns
+newtype UploadWithRoot = UploadWithRoot { unRootUpload :: Upload } deriving (Eq, Ord, Read, Show, Typeable)
 
 instance FromJSON UploadWithRoot where
   parseJSON (Object v) = UploadWithRoot <$> v .: "upload"
@@ -236,6 +283,7 @@ instance FromJSON UploadWithRoot where
 ---------- General Purpose Types
 type Id = Integer
 
+-- |Utility type to normalize the non-standard date format that the Campfire API returns
 newtype CampfireTime = CampfireTime { 
                          fromCampfireTime :: UTCTime 
                        } deriving (Eq, Ord, Read, Show, Typeable, FormatTime)