Document Data.BalancedStream.yieldBalancedM

And Server.HtmlStream.{mkStartEndElem, streamTagBalancedM}
runeksvendsen · Oct 25, 2024 · 603cdf6 · 603cdf6
1 parent 74791d2
commit 603cdf6
Show file tree

Hide file tree

Showing 2 changed files with 22 additions and 2 deletions.
diff --git a/src/server/Data/BalancedStream.hs b/src/server/Data/BalancedStream.hs
@@ -126,7 +126,13 @@ yieldBalanced
 yieldBalanced a1 a2 =
   BalancedStream $ (,[[a2]]) <$> S.yield a1
 
--- | TODO: allows @BEFORE { blah } AFTER@ instead of @BEFORE { blah AFTER }@.
+-- | Insert a 'BalancedStream' between an initial an terminating stream item.
+--
+-- Example:
+--
+-- >>> let stream = yieldBalancedM "START" "END" $ yield "1" >> yield "2" >> yield "3"
+-- >>> concat $ Data.Functor.Identity.runIdentity $ Streaming.Prelude.toList_ (toStream stream)
+-- "START123END"
 yieldBalancedM
   :: Monad m
   => a -- ^ Initial item

diff --git a/src/server/Server/HtmlStream.hs b/src/server/Server/HtmlStream.hs
@@ -49,6 +49,12 @@ streamHtml
   -> HtmlStream m ()
 streamHtml = HtmlStream . yield
 
+-- | Create a start and end 'Lucid.Html' tag.
+--
+-- Example:
+--
+-- >>> mkStartEndElem "p"
+-- (<p>,</p>)
 mkStartEndElem
   :: T.Text
   -> (Lucid.Html (), Lucid.Html ()) -- ^ (start, end) tags
@@ -77,6 +83,14 @@ streamTagBalancedAttr tag attrs = HtmlStream $
   where
     (start, end) = mkStartEndElem tag
 
+-- | Put a 'HtmlStream' inside a tag.
+--
+-- Example:
+--
+-- >>> import Lucid
+-- >>> let stream = streamTagBalancedM "html" $ streamTagBalancedM "body" $ streamHtml (p_ "hello world")
+-- >>> mconcat $ Data.Functor.Identity.runIdentity $ Streaming.Prelude.toList_ (Server.HtmlStream.toStream stream)
+-- <html><body><p>hello world</p></body></html>
 streamTagBalancedM
   :: Monad m
   => T.Text -- ^ tag
@@ -87,7 +101,7 @@ streamTagBalancedM tag s = HtmlStream $
   where
     (start, end) = mkStartEndElem tag
 
--- | Same as 'streamTagBalanced' but accepts attributes
+-- | Same as 'streamTagBalanced' but accepts tag attributes
 streamTagBalancedAttrM
   :: Monad m
   => T.Text -- ^ tag