Merge pull request #195 from reflex-frp/rmm-docallthethings2

Another batch of doc comments

Author: luigy

src/Data/Map/Misc.hs

@@ -1,4 +1,5 @@
 {-# LANGUAGE LambdaCase #-}
+-- | Additional functions for manipulating 'Map's.
 module Data.Map.Misc
   (
   -- * Working with Maps
@@ -10,20 +11,28 @@ module Data.Map.Misc
   ) where
 
 import Data.Align
-import Data.Either (isLeft)
 import Data.Map (Map)
 import qualified Data.Map as Map
 import Data.Maybe
 import Data.Set (Set)
 import qualified Data.Set as Set
 import Data.These
 
+-- |Produce a @'Map' k (Maybe v)@ by comparing two @'Map' k v@s, @old@ and @new@ respectively. @Just@ represents an association present in @new@ and @Nothing@
+-- represents an association only present in @old@ but no longer present in @new@.
+--
+-- Similar to 'diffMap' but doesn't require 'Eq' on the values, thus can't tell if a value has changed or not.
 diffMapNoEq :: (Ord k) => Map k v -> Map k v -> Map k (Maybe v)
 diffMapNoEq olds news = flip Map.mapMaybe (align olds news) $ \case
   This _ -> Just Nothing
   These _ new -> Just $ Just new
   That new -> Just $ Just new
 
+-- |Produce a @'Map' k (Maybe v)@ by comparing two @'Map' k v@s, @old@ and @new respectively. @Just@ represents an association present in @new@ and either not
+-- present in @old@ or where the value has changed. @Nothing@ represents an association only present in @old@ but no longer present in @new@.
+--
+-- See also 'diffMapNoEq' for a similar but weaker version which does not require 'Eq' on the values but thus can't indicated a value not changing between
+-- @old@ and @new@ with @Nothing@.
 diffMap :: (Ord k, Eq v) => Map k v -> Map k v -> Map k (Maybe v)
 diffMap olds news = flip Map.mapMaybe (align olds news) $ \case
   This _ -> Just Nothing
@@ -32,23 +41,29 @@ diffMap olds news = flip Map.mapMaybe (align olds news) $ \case
     | otherwise -> Just $ Just new
   That new -> Just $ Just new
 
+-- |Given a @'Map' k (Maybe v)@ representing keys to insert/update (@Just@) or delete (@Nothing@), produce a new map from the given input @'Map' k v@.
+--
+-- See also 'Reflex.Patch.Map' and 'Reflex.Patch.MapWithMove'.
 applyMap :: Ord k => Map k (Maybe v) -> Map k v -> Map k v
 applyMap patch old = insertions `Map.union` (old `Map.difference` deletions)
   where (deletions, insertions) = mapPartitionEithers $ maybeToEither <$> patch
         maybeToEither = \case
           Nothing -> Left ()
           Just r -> Right r
 
+-- |Split a @'Map' k (Either a b)@ into @Map k a@ and @Map k b@, equivalent to @'Map.mapEither' id@
 mapPartitionEithers :: Map k (Either a b) -> (Map k a, Map k b)
-mapPartitionEithers m = (fromLeft <$> ls, fromRight <$> rs)
-  where (ls, rs) = Map.partition isLeft m
-        fromLeft (Left l) = l
-        fromLeft _ = error "mapPartitionEithers: fromLeft received a Right value; this should be impossible"
-        fromRight (Right r) = r
-        fromRight _ = error "mapPartitionEithers: fromRight received a Left value; this should be impossible"
+mapPartitionEithers = Map.mapEither id
 
--- | Apply a map patch to a set
--- > applyMapKeysSet patch (Map.keysSet m) == Map.keysSet (applyMap patch m)
+-- |Given a @'Map' k (Maybe v)@ representing keys to insert/update (@Just@) or delete (@Nothing@), produce a new @'Set' k@ from the given input set.
+--
+-- Equivalent to:
+--
+-- @
+--     applyMapKeysSet patch ('Map.keysSet' m) == 'Map.keysSet' ('applyMap' patch m)
+-- @
+--
+-- but avoids the intervening @Map@ and needs no values.
 applyMapKeysSet :: Ord k => Map k (Maybe v) -> Set k -> Set k
 applyMapKeysSet patch old = Map.keysSet insertions `Set.union` (old `Set.difference` Map.keysSet deletions)
   where (insertions, deletions) = Map.partition isJust patch

src/Reflex/FastWeak.hs

@@ -5,6 +5,15 @@
 {-# LANGUAGE ForeignFunctionInterface #-}
 {-# LANGUAGE JavaScriptFFI #-}
 #endif
+
+-- | 'FastWeak' is a weak pointer to some value, and 'FastWeakTicket' ensures the value
+-- referred to by a 'FastWeak' stays live while the ticket is held (live).
+--
+-- On GHC or GHCJS when not built with the @fast-weak@ cabal flag, 'FastWeak' is a wrapper
+-- around the simple version of 'System.Mem.Weak.Weak' where the key and value are the same.
+--
+-- On GHCJS when built with the @fast-weak@ cabal flag, 'FastWeak' is implemented directly
+-- in JS using @h$FastWeak@ and @h$FastWeakTicket@ which are a nonstandard part of the GHCJS RTS.
 module Reflex.FastWeak
   ( FastWeakTicket
   , FastWeak
@@ -35,29 +44,57 @@ import System.Mem.Weak
 
 
 #ifdef GHCJS_FAST_WEAK
+-- | A 'FastWeak' which has been promoted to a strong reference. 'getFastWeakTicketValue'
+-- can be used to get the referred to value without fear of @Nothing,
+-- and 'getFastWeakTicketWeak' can be used to get the weak version.
+--
+-- Implemented by way of special support in the GHCJS RTS, @h$FastWeakTicket@.
 newtype FastWeakTicket a = FastWeakTicket JSVal
 
+-- | A reference to some value which can be garbage collected if there are only
+-- weak references to the value left.
+--
+-- 'getFastWeakValue' can be used to try and obtain a strong reference to the value.
+--
+-- The value in a @FastWeak@ can also be kept alive by obtaining a 'FastWeakTicket' using
+-- 'getFastWeakTicket' if the value hasn't been collected yet.
+--
+-- Implemented by way of special support in the GHCJS RTS, @h$FastWeak@.
 newtype FastWeak a = FastWeak JSVal
 
 -- Just designed to mirror JSVal, so that we can unsafeCoerce between the two
 data Val a = Val { unVal :: a }
 
--- | Coerce a JSVal that represents the heap object of a value of type 'a' into a value of type 'a'
+-- | Coerce a JSVal that represents the heap object of a value of type @a@ into a value of type @a@
 unsafeFromRawJSVal :: JSVal -> a
 unsafeFromRawJSVal v = unVal (unsafeCoerce v)
 
+-- | Coerce a heap object of type @a@ into a 'JSVal' which represents that object.
 unsafeToRawJSVal :: a -> JSVal
 unsafeToRawJSVal v = unsafeCoerce (Val v)
 #else
+-- | A 'FastWeak' which has been promoted to a strong reference. 'getFastWeakTicketValue'
+-- can be used to get the referred to value without fear of @Nothing@,
+-- and 'getFastWeakTicketWeak' can be used to get the weak version.
 data FastWeakTicket a = FastWeakTicket
   { _fastWeakTicket_val :: !a
   , _fastWeakTicket_weak :: {-# UNPACK #-} !(Weak a)
   }
 
+-- | A reference to some value which can be garbage collected if there are only weak references to the value left.
+--
+-- 'getFastWeakValue' can be used to try and obtain a strong reference to the value.
+--
+-- The value in a @FastWeak@ can also be kept alive by obtaining a 'FastWeakTicket' using 'getFastWeakTicket'
+-- if the value hasn't been collected yet.
+--
+-- Synonymous with 'Weak'.
 type FastWeak a = Weak a
 #endif
 
--- This needs to be in IO so we know that we've relinquished the ticket
+-- | Return the @a@ kept alive by the given 'FastWeakTicket'.
+--
+-- This needs to be in IO so we know that we've relinquished the ticket.
 getFastWeakTicketValue :: FastWeakTicket a -> IO a
 #ifdef GHCJS_FAST_WEAK
 getFastWeakTicketValue t = do
@@ -69,6 +106,8 @@ foreign import javascript unsafe "$r = $1.val;" js_ticketVal :: FastWeakTicket a
 getFastWeakTicketValue = return . _fastWeakTicket_val
 #endif
 
+-- | Get the value referred to by a 'FastWeak' if it hasn't yet been collected,
+-- or @Nothing@ if it has been collected.
 getFastWeakValue :: FastWeak a -> IO (Maybe a)
 #ifdef GHCJS_FAST_WEAK
 getFastWeakValue w = do
@@ -84,6 +123,9 @@ foreign import javascript unsafe "$r = ($1.ticket === null) ? null : $1.ticket.v
 getFastWeakValue = deRefWeak
 #endif
 
+-- | Try to create a 'FastWeakTicket' for the given 'FastWeak' which will ensure the value referred
+-- remains alive. Returns @Just@ if the value hasn't been collected
+-- and a ticket can therefore be obtained, @Nothing@ if it's been collected.
 getFastWeakTicket :: forall a. FastWeak a -> IO (Maybe (FastWeakTicket a))
 #ifdef GHCJS_FAST_WEAK
 getFastWeakTicket w = do
@@ -103,8 +145,11 @@ getFastWeakTicket w = do
       }
 #endif
 
--- I think it's fine if this is lazy - it'll retain the 'a', but so would the output; we just need to make sure it's forced before we start relying on the associated FastWeak to actually be weak
+-- | Create a 'FastWeakTicket' directly from a value, creating a 'FastWeak' in the process
+-- which can be obtained with 'getFastWeakTicketValue'.
 mkFastWeakTicket :: a -> IO (FastWeakTicket a)
+-- I think it's fine if this is lazy - it'll retain the 'a', but so would the output; we just need to make sure it's forced before we start relying on the
+-- associated FastWeak to actually be weak
 #ifdef GHCJS_FAST_WEAK
 mkFastWeakTicket v = js_fastWeakTicket (unsafeToRawJSVal v)
 
@@ -119,11 +164,16 @@ mkFastWeakTicket v = do
     }
 #endif
 
+-- | Demote a 'FastWeakTicket'; which ensures the value is alive, to a 'FastWeak' which doesn't.
+-- Note that unless the ticket for the same 'FastWeak' is held in some other way
+-- the value might be collected immediately.
+getFastWeakTicketWeak :: FastWeakTicket a -> IO (FastWeak a)
 -- Needs IO so that it can force the value - otherwise, could end up with a reference to the Ticket, which would retain the value
 #ifdef GHCJS_FAST_WEAK
-foreign import javascript unsafe "$r = $1.weak;" getFastWeakTicketWeak :: FastWeakTicket a -> IO (FastWeak a)
+foreign import javascript unsafe "$r = $1.weak;" getFastWeakTicketWeak' :: FastWeakTicket a -> IO (FastWeak a)
+{-# INLINE getFastWeakTicketWeak #-}
+getFastWeakTicketWeak = getFastWeakTicketWeak'
 #else
-getFastWeakTicketWeak :: FastWeakTicket a -> IO (FastWeak a)
 getFastWeakTicketWeak = return . _fastWeakTicket_weak
 #endif
 

src/Reflex/Patch/DMap.hs

@@ -5,6 +5,7 @@
 {-# LANGUAGE ScopedTypeVariables #-}
 {-# LANGUAGE StandaloneDeriving #-}
 {-# LANGUAGE TypeFamilies #-}
+-- | 'Patch'es on 'DMap' that consist only of insertions (or overwrites) and deletions.
 module Reflex.Patch.DMap where
 
 import Reflex.Patch.Class
@@ -20,14 +21,16 @@ import qualified Data.Map as Map
 import Data.Semigroup (Semigroup (..))
 import Data.Some (Some)
 
--- | A set of changes to a 'DMap'.  Any element may be inserted/updated or
--- deleted.
+-- | A set of changes to a 'DMap'.  Any element may be inserted/updated or deleted.
+-- Insertions are represented as @'ComposeMaybe' (Just value)@,
+-- while deletions are represented as @'ComposeMaybe' Nothing@.
 newtype PatchDMap k v = PatchDMap { unPatchDMap :: DMap k (ComposeMaybe v) }
 
 deriving instance GCompare k => Semigroup (PatchDMap k v)
 
 deriving instance GCompare k => Monoid (PatchDMap k v)
 
+-- | Apply the insertions or deletions to a given 'DMap'.
 instance GCompare k => Patch (PatchDMap k v) where
   type PatchTarget (PatchDMap k v) = DMap k v
   apply (PatchDMap diff) old = Just $! insertions `DMap.union` (old `DMap.difference` deletions) --TODO: return Nothing sometimes --Note: the strict application here is critical to ensuring that incremental merges don't hold onto all their prerequisite events forever; can we make this more robust?
@@ -37,32 +40,43 @@ instance GCompare k => Patch (PatchDMap k v) where
             Nothing -> Just $ Constant ()
             Just _ -> Nothing
 
+-- | Map a function @v a -> v' a@ over any inserts/updates in the given
+-- @'PatchDMap' k v@ to produce a @'PatchDMap' k v'@.
 mapPatchDMap :: (forall a. v a -> v' a) -> PatchDMap k v -> PatchDMap k v'
 mapPatchDMap f (PatchDMap p) = PatchDMap $ DMap.map (ComposeMaybe . fmap f . getComposeMaybe) p
 
-traversePatchDMap :: Applicative m => (forall a. v a -> m (v' a)) -> PatchDMap k v -> m (PatchDMap k v')
+-- | Map an effectful function @v a -> f (v' a)@ over any inserts/updates in the given
+-- @'PatchDMap' k v@ to produce a @'PatchDMap' k v'@.
+traversePatchDMap :: Applicative f => (forall a. v a -> f (v' a)) -> PatchDMap k v -> f (PatchDMap k v')
 traversePatchDMap f = traversePatchDMapWithKey $ const f
 
+-- | Map an effectful function @k a -> v a -> f (v' a)@ over any inserts/updates
+-- in the given @'PatchDMap' k v@ to produce a @'PatchDMap' k v'@.
 traversePatchDMapWithKey :: Applicative m => (forall a. k a -> v a -> m (v' a)) -> PatchDMap k v -> m (PatchDMap k v')
 traversePatchDMapWithKey f (PatchDMap p) = PatchDMap <$> DMap.traverseWithKey (\k (ComposeMaybe v) -> ComposeMaybe <$> traverse (f k) v) p
 
+-- | Weaken a @'PatchDMap' k v@ to a @'PatchMap' (Some k) v'@ using a function
+-- @v a -> v'@ to weaken each value contained in the patch.
 weakenPatchDMapWith :: (forall a. v a -> v') -> PatchDMap k v -> PatchMap (Some k) v'
 weakenPatchDMapWith f (PatchDMap p) = PatchMap $ weakenDMapWith (fmap f . getComposeMaybe) p
 
-patchDMapToPatchMapWith :: (f v -> v') -> PatchDMap (Const2 k v) f -> PatchMap k v'
+-- | Convert a weak @'PatchDMap' ('Const2' k a) v@ where the @a@ is known by way of
+-- the @Const2@ into a @'PatchMap' k v'@ using a rank 1 function @v a -> v'@.
+patchDMapToPatchMapWith :: (v a -> v') -> PatchDMap (Const2 k a) v -> PatchMap k v'
 patchDMapToPatchMapWith f (PatchDMap p) = PatchMap $ dmapToMapWith (fmap f . getComposeMaybe) p
 
-const2PatchDMapWith :: forall k v f a. (v -> f a) -> PatchMap k v -> PatchDMap (Const2 k a) f
+-- | Convert a @'PatchMap' k v@ into a @'PatchDMap' ('Const2' k a) v'@ using a function @v -> v' a@.
+const2PatchDMapWith :: forall k v v' a. (v -> v' a) -> PatchMap k v -> PatchDMap (Const2 k a) v'
 const2PatchDMapWith f (PatchMap p) = PatchDMap $ DMap.fromDistinctAscList $ g <$> Map.toAscList p
-  where g :: (k, Maybe v) -> DSum (Const2 k a) (ComposeMaybe f)
+  where g :: (k, Maybe v) -> DSum (Const2 k a) (ComposeMaybe v')
         g (k, e) = Const2 k :=> ComposeMaybe (f <$> e)
 
+-- | Convert a @'PatchIntMap' v@ into a @'PatchDMap' ('Const2' Int a) v'@ using a function @v -> v' a@.
 const2IntPatchDMapWith :: forall v f a. (v -> f a) -> PatchIntMap v -> PatchDMap (Const2 IntMap.Key a) f
 const2IntPatchDMapWith f (PatchIntMap p) = PatchDMap $ DMap.fromDistinctAscList $ g <$> IntMap.toAscList p
   where g :: (IntMap.Key, Maybe v) -> DSum (Const2 IntMap.Key a) (ComposeMaybe f)
         g (k, e) = Const2 k :=> ComposeMaybe (f <$> e)
 
--- | Get the values that will be deleted if the given patch is applied to the
--- given 'DMap'.  Includes values that will be replaced.
+-- | Get the values that will be replaced or deleted if the given patch is applied to the given 'DMap'.
 getDeletions :: GCompare k => PatchDMap k v -> DMap k v' -> DMap k v'
 getDeletions (PatchDMap p) m = DMap.intersectionWithKey (\_ v _ -> v) m p

src/Reflex/Patch/DMapWithMove.hs

@@ -104,6 +104,7 @@ validationErrorsForPatchDMapWithMove m =
           Just $ "unbalanced move at source key " <> gshow src <> " supposedly going to " <> gshow dst <> " but destination key is not moving"
     unbalancedMove _ = Nothing
 
+-- |Test whether two @'PatchDMapWithMove' k v@ contain the same patch operations.
 instance EqTag k (NodeInfo k v) => Eq (PatchDMapWithMove k v) where
   PatchDMapWithMove a == PatchDMapWithMove b = a == b
 
@@ -341,6 +342,7 @@ const2PatchDMapWithMoveWith f (PatchMapWithMove p) = PatchDMapWithMove $ DMap.fr
           , _nodeInfo_to = ComposeMaybe $ Const2 <$> MapWithMove._nodeInfo_to ni
           }
 
+-- | Apply the insertions, deletions, and moves to a given 'DMap'.
 instance GCompare k => Patch (PatchDMapWithMove k v) where
   type PatchTarget (PatchDMapWithMove k v) = DMap k v
   apply (PatchDMapWithMove p) old = Just $! insertions `DMap.union` (old `DMap.difference` deletions) --TODO: return Nothing sometimes --Note: the strict application here is critical to ensuring that incremental merges don't hold onto all their prerequisite events forever; can we make this more robust?
@@ -356,8 +358,7 @@ instance GCompare k => Patch (PatchDMapWithMove k v) where
             From_Delete -> Just $ Constant ()
             _ -> Nothing
 
--- | Get the values that will be deleted or moved if the given patch is applied
--- to the given 'DMap'.
+-- | Get the values that will be replaced, deleted, or moved if the given patch is applied to the given 'DMap'.
 getDeletionsAndMoves :: GCompare k => PatchDMapWithMove k v -> DMap k v' -> DMap k (Product v' (ComposeMaybe k))
 getDeletionsAndMoves (PatchDMapWithMove p) m = DMap.intersectionWithKey f m p
   where f _ v ni = Pair v $ _nodeInfo_to ni

src/Reflex/Patch/IntMap.hs

@@ -4,6 +4,8 @@
 {-# LANGUAGE DeriveTraversable #-}
 {-# LANGUAGE GeneralizedNewtypeDeriving #-}
 {-# LANGUAGE TypeFamilies #-}
+-- | Module containing 'PatchIntMap', a 'Patch' for 'IntMap' which allows for
+-- insert/update or delete of associations.
 module Reflex.Patch.IntMap where
 
 import Data.IntMap.Strict (IntMap)
@@ -12,8 +14,12 @@ import Data.Maybe
 import Data.Semigroup
 import Reflex.Patch.Class
 
+-- | 'Patch' for 'IntMap' which represents insertion or deletion of keys in the mapping.
+-- Internally represented by 'IntMap (Maybe a)', where @Just@ means insert/update
+-- and @Nothing@ means delete.
 newtype PatchIntMap a = PatchIntMap (IntMap (Maybe a)) deriving (Functor, Foldable, Traversable, Monoid)
 
+-- | Apply the insertions or deletions to a given 'IntMap'.
 instance Patch (PatchIntMap a) where
   type PatchTarget (PatchIntMap a) = IntMap a
   apply (PatchIntMap p) v = if IntMap.null p then Nothing else Just $
@@ -36,14 +42,26 @@ instance Semigroup (PatchIntMap v) where
     GT -> x
 #endif
 
-traverseIntMapPatchWithKey :: Applicative t => (Int -> a -> t b) -> PatchIntMap a -> t (PatchIntMap b)
+-- | Map a function @Int -> a -> b@ over all @a@s in the given @'PatchIntMap' a@
+-- (that is, all inserts/updates), producing a @PatchIntMap b@.
+mapIntMapPatchWithKey :: (Int -> a -> b) -> PatchIntMap a -> PatchIntMap b
+mapIntMapPatchWithKey f (PatchIntMap m) = PatchIntMap $ IntMap.mapWithKey (\ k mv -> f k <$> mv) m
+
+-- | Map an effectful function @Int -> a -> f b@ over all @a@s in the given @'PatchIntMap' a@
+-- (that is, all inserts/updates), producing a @f (PatchIntMap b)@.
+traverseIntMapPatchWithKey :: Applicative f => (Int -> a -> f b) -> PatchIntMap a -> f (PatchIntMap b)
 traverseIntMapPatchWithKey f (PatchIntMap m) = PatchIntMap <$> IntMap.traverseWithKey (\k mv -> traverse (f k) mv) m
 
+-- | Extract all @a@s inserted/updated by the given @'PatchIntMap' a@.
 patchIntMapNewElements :: PatchIntMap a -> [a]
 patchIntMapNewElements (PatchIntMap m) = catMaybes $ IntMap.elems m
 
+-- | Convert the given @'PatchIntMap' a@ into an @'IntMap' a@ with all
+-- the inserts/updates in the given patch.
 patchIntMapNewElementsMap :: PatchIntMap a -> IntMap a
 patchIntMapNewElementsMap (PatchIntMap m) = IntMap.mapMaybe id m
 
+-- | Subset the given @'IntMap' a@ to contain only the keys that would be
+-- deleted by the given @'PatchIntMap' a@.
 getDeletions :: PatchIntMap v -> IntMap v' -> IntMap v'
 getDeletions (PatchIntMap m) v = IntMap.intersection v m

src/Reflex/Patch/Map.hs

@@ -18,8 +18,7 @@ import Data.Semigroup
 newtype PatchMap k v = PatchMap { unPatchMap :: Map k (Maybe v) }
   deriving (Show, Read, Eq, Ord)
 
--- | Applying a 'PatchMap' will update the 'Map' by performing the insertions
--- and deletions specified
+-- | Apply the insertions or deletions to a given 'Map'.
 instance Ord k => Patch (PatchMap k v) where
   type PatchTarget (PatchMap k v) = Map k v
   {-# INLINABLE apply #-}