Merge pull request #1155 from chreekat/enclosure-doc

Document feed entry enclosures

yesod-newsfeed/ChangeLog.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.6
+
+* Create new datatype `EntryEnclosure` for self-documentation of `feedEntryEnclosure`.
+
 ## 1.5
 
 ### Yesod/FeedTypes.hs

yesod-newsfeed/Yesod/AtomFeed.hs

@@ -28,7 +28,6 @@ module Yesod.AtomFeed
 
 import Yesod.Core
 import Yesod.FeedTypes
-import Text.Hamlet (hamlet)
 import qualified Data.ByteString.Char8 as S8
 import Data.Text (Text)
 import Data.Text.Lazy (toStrict)
@@ -86,7 +85,9 @@ entryTemplate FeedEntry {..} render = Element "entry" Map.empty $ map NodeElemen
     ++
     case feedEntryEnclosure of
         Nothing -> []
-        Just (route, _, _) -> [Element "link" (Map.fromList [("rel", "enclosure"), ("href", render route)]) []]
+        Just (EntryEnclosure{..}) ->
+            [Element "link" (Map.fromList [("rel", "enclosure")
+                                          ,("href", render enclosedUrl)]) []]
 
 -- | Generates a link tag in the head of a widget.
 atomLink :: MonadWidget m

yesod-newsfeed/Yesod/FeedTypes.hs

@@ -1,6 +1,7 @@
 module Yesod.FeedTypes
     ( Feed (..)
     , FeedEntry (..)
+    , EntryEnclosure (..)
     ) where
 
 import Text.Hamlet      (Html)
@@ -27,11 +28,27 @@ data Feed url = Feed
     , feedEntries     :: [FeedEntry url]
     }
 
+-- | RSS and Atom allow for linked content to be enclosed in a feed entry.
+-- This represents the enclosed content.
+--
+-- Atom feeds ignore 'enclosedSize' and 'enclosedMimeType'.
+--
+-- @since 1.6
+data EntryEnclosure url = EntryEnclosure
+    { enclosedUrl :: url
+    , enclosedSize :: Int -- ^ Specified in bytes
+    , enclosedMimeType :: Text
+    }
+
 -- | Each feed entry
 data FeedEntry url = FeedEntry
     { feedEntryLink    :: url
     , feedEntryUpdated :: UTCTime
     , feedEntryTitle   :: Text
     , feedEntryContent :: Html
-    , feedEntryEnclosure :: Maybe (url, Int, Text)
+    , feedEntryEnclosure :: Maybe (EntryEnclosure url)
+      -- ^ Allows enclosed data: RSS \<enclosure> or Atom \<link
+      -- rel=enclosure>
+      --
+      -- @since 1.5
     }

yesod-newsfeed/Yesod/RssFeed.hs

@@ -24,7 +24,6 @@ module Yesod.RssFeed
 
 import Yesod.Core
 import Yesod.FeedTypes
-import Text.Hamlet (hamlet)
 import qualified Data.ByteString.Char8 as S8
 import Data.Text (Text, pack)
 import Data.Text.Lazy (toStrict)
@@ -87,7 +86,11 @@ entryTemplate FeedEntry {..} render = Element "item" Map.empty $ map NodeElement
     ++
     case feedEntryEnclosure of
         Nothing -> []
-        Just (route, length, mime) -> [Element "enclosure" (Map.fromList [("type", mime), ("length", pack $ show length), ("url", render route)]) []]
+        Just (EntryEnclosure{..}) -> [
+            Element "enclosure"
+                    (Map.fromList [("type", enclosedMimeType)
+                                  ,("length", pack $ show enclosedSize)
+                                  ,("url", render enclosedUrl)]) []]
 
 -- | Generates a link tag in the head of a widget.
 rssLink :: MonadWidget m

yesod-newsfeed/yesod-newsfeed.cabal

@@ -1,5 +1,5 @@
 name:            yesod-newsfeed
-version:         1.5
+version:         1.6
 license:         MIT
 license-file:    LICENSE
 author:          Michael Snoyman, Patrick Brisbin