29ed3c1 · reflex · git.iko.soy

git.iko.soy/reflex

Merge pull request #257 from reflex-frp/dn-haddock-fixes

Fixes for haddocks

commit29ed3c1b468bae8fdd0843e541b713df258b18ea authorLuigy Leon <luichi.19@gmail.com> dateFri 18 Jan 2019, 13:38 (8 years ago) parenta770933 3e5e284

6 files changed+41−42

compare with develop

unifiedsplit

src/Data/FastWeakBag.hs+2−2 src/Data/WeakBag.hs+2−2 src/Reflex/Class.hs+12−13 src/Reflex/Collection.hs+4−4 src/Reflex/Dynamic.hs+17−17 src/Reflex/Pure.hs+4−4

src/Data/FastWeakBag.hs+2−2

@@ -42,8 +42,8 @@ import Data.IORef

4242import System.Mem.Weak

4343#endif

4444

45−-- | A @FastWeakBag a@ holds a set of values of type @a@, but does not retain them -

46−-- that is, they can still be garbage-collected. As long as the @a@s remain

45+-- | A 'FastWeakBag' holds a set of values of type @/a/@, but does not retain them -

46+-- that is, they can still be garbage-collected. As long as the @/a/@ values remain

4747-- alive, the 'FastWeakBag' will continue to refer to them.

4848#ifdef GHCJS_FAST_WEAK

4949newtype FastWeakBag a = FastWeakBag JSVal

src/Data/WeakBag.hs+2−2

@@ -31,8 +31,8 @@ import qualified Data.IntMap.Strict as IntMap

3131import Data.IORef

3232import System.Mem.Weak

3333

34−-- | A @WeakBag a@ holds a set of values of type @a@, but does not retain them -

35−-- that is, they can still be garbage-collected. As long as the @a@s remain

34+-- | A 'WeakBag' holds a set of values of type @/a/@, but does not retain them -

35+-- that is, they can still be garbage-collected. As long as the @/a/@ values remain

3636-- alive, the 'WeakBag' will continue to refer to them.

3737data WeakBag a = WeakBag

3838 { _weakBag_nextId :: {-# UNPACK #-} !(IORef Int) --TODO: what if this wraps around?

src/Reflex/Class.hs+12−13

@@ -34,10 +34,9 @@ module Reflex.Class

3434 , coerceDynamic

3535 , MonadSample (..)

3636 , MonadHold (..)

37− -- ** 'fan'-related types

37+ -- ** 'fan' related types

3838 , EventSelector (..)

3939 , EventSelectorInt (..)

40− -- ** 'Incremental'-related types

4140 -- * Convenience functions

4241 , constDyn

4342 , pushAlways

@@ -201,7 +200,7 @@ import qualified Reflex.Patch.MapWithMove as PatchMapWithMove

201200import Debug.Trace (trace)

202201

203202-- | The 'Reflex' class contains all the primitive functionality needed for

204−-- Functional Reactive Programming (FRP). The @t@ type parameter indicates

203+-- Functional Reactive Programming (FRP). The @/t/@ type parameter indicates

205204-- which "timeline" is in use. Timelines are fully-independent FRP contexts,

206205-- and the type of the timeline determines the FRP engine to be used. For most

207206-- purposes, the 'Reflex.Spider' implementation is recommended.

@@ -267,7 +266,7 @@ class ( MonadHold t (PushM t)

267266 -- | Create a new 'Dynamic'. The given 'PullM' must always return the most

268267 -- recent firing of the given 'Event', if any.

269268 unsafeBuildDynamic :: PullM t a -> Event t a -> Dynamic t a

270− -- | Create a new 'Incremental'. The given 'PullM''s value must always change

269+ -- | Create a new 'Incremental'. The given "PullM"'s value must always change

271270 -- in the same way that the accumulated application of patches would change

272271 -- that value.

273272 unsafeBuildIncremental :: Patch p => PullM t (PatchTarget p) -> Event t p -> Incremental t p

@@ -310,7 +309,7 @@ coerceDynamic :: (Reflex t, Coercible a b) => Dynamic t a -> Dynamic t b

310309coerceDynamic = coerceWith $ dynamicCoercion Coercion

311310

312311-- | Construct a 'Dynamic' from a 'Behavior' and an 'Event'. The 'Behavior'

313−-- _must_ change when and only when the 'Event' fires, such that the

312+-- __must__ change when and only when the 'Event' fires, such that the

314313-- 'Behavior''s value is always equal to the most recent firing of the 'Event';

315314-- if this is not the case, the resulting 'Dynamic' will behave

316315-- nondeterministically.

@@ -338,7 +337,7 @@ class MonadSample t m => MonadHold t m where

338337 -- value and will be updated whenever the given 'Event' occurs. The update

339338 -- takes effect immediately after the 'Event' occurs; if the occurrence that

340339 -- sets the 'Behavior' (or one that is simultaneous with it) is used to sample

341− -- the 'Behavior', it will see the _old_ value of the 'Behavior', not the new

340+ -- the 'Behavior', it will see the __old__ value of the 'Behavior', not the new

342341 -- one.

343342 hold :: a -> Event t a -> m (Behavior t a)

344343 default hold :: (m ~ f m', MonadTrans f, MonadHold t m') => a -> Event t a -> m (Behavior t a)

@@ -641,7 +640,7 @@ headTailE e = do

641640-- event returns 'True'.

642641--

643642-- Starting at the current time, fire all the occurrences of the 'Event' for

644−-- which the given predicate returns 'True'. When 'False' first is returned,

643+-- which the given predicate returns 'True'. When first 'False' is returned,

645644-- do not fire, and permanently stop firing, even if 'True' values would have

646645-- been encountered later.

647646takeWhileE

@@ -656,7 +655,7 @@ takeWhileE f = takeWhileJustE $ \v -> guard (f v) $> v

656655-- event returns 'Just b'.

657656--

658657-- Starting at the current time, fire all the occurrences of the 'Event' for

659−-- which the given predicate returns 'Just b'. When 'Nothing' first is returned,

658+-- which the given predicate returns 'Just b'. When first 'Nothing' is returned,

660659-- do not fire, and permanently stop firing, even if 'Just b' values would have

661660-- been encountered later.

662661takeWhileJustE

@@ -829,7 +828,7 @@ fanMap = fan . fmap mapToDMap

829828

830829-- | Switches to the new event whenever it receives one. Only the old event is

831830-- considered the moment a new one is switched in; the output event will fire at

832−-- that moment if only if the old event does.

831+-- that moment only if the old event does.

833832--

834833-- Because the simultaneous firing case is irrelevant, this function imposes

835834-- laxer "timing requirements" on the overall circuit, avoiding many potential

@@ -875,13 +874,13 @@ coincidencePatchMap e = fmapCheap PatchMap $ coincidence $ ffor e $ \(PatchMap m

875874 Nothing -> fmapCheap (const Nothing) e

876875 Just ev -> leftmost [fmapCheap Just ev, fmapCheap (const Nothing) e]

877876

878−-- | See 'coincicencePatchMap'

877+-- | See 'coincidencePatchMap'

879878coincidencePatchIntMap :: Reflex t => Event t (PatchIntMap (Event t v)) -> Event t (PatchIntMap v)

880879coincidencePatchIntMap e = fmapCheap PatchIntMap $ coincidence $ ffor e $ \(PatchIntMap m) -> mergeIntMap $ ffor m $ \case

881880 Nothing -> fmapCheap (const Nothing) e

882881 Just ev -> leftmost [fmapCheap Just ev, fmapCheap (const Nothing) e]

883882

884−-- | See 'coincicencePatchMap'

883+-- | See 'coincidencePatchMap'

885884coincidencePatchMapWithMove :: (Reflex t, Ord k) => Event t (PatchMapWithMove k (Event t v)) -> Event t (PatchMapWithMove k v)

886885coincidencePatchMapWithMove e = fmapCheap unsafePatchMapWithMove $ coincidence $ ffor e $ \p -> mergeMap $ ffor (unPatchMapWithMove p) $ \ni -> case PatchMapWithMove._nodeInfo_from ni of

887886 PatchMapWithMove.From_Delete -> fforCheap e $ \_ ->

@@ -942,7 +941,7 @@ zipDyn = zipDynWith (,)

942941

943942-- | Combine two 'Dynamic's with a combining function. The result will change

944943-- whenever either (or both) input 'Dynamic' changes.

945−-- More efficient than liftA2.

944+-- More efficient than 'liftA2'.

946945zipDynWith :: Reflex t => (a -> b -> c) -> Dynamic t a -> Dynamic t b -> Dynamic t c

947946zipDynWith f da db =

948947 let eab = align (updated da) (updated db)

@@ -973,7 +972,7 @@ instance (Reflex t, Monoid a) => Monoid (Dynamic t a) where

973972

974973-- | This function converts a 'DMap' whose elements are 'Dynamic's into a

975974-- 'Dynamic' 'DMap'. Its implementation is more efficient than doing the same

976−-- through the use of multiple uses of 'zipWithDyn' or 'Applicative' operators.

975+-- through the use of multiple uses of 'zipDynWith' or 'Applicative' operators.

977976distributeDMapOverDynPure :: forall t k. (Reflex t, GCompare k) => DMap k (Dynamic t) -> Dynamic t (DMap k Identity)

978977distributeDMapOverDynPure dm = case DMap.toList dm of

979978 [] -> constDyn DMap.empty

src/Reflex/Collection.hs+4−4

@@ -139,10 +139,10 @@ listWithKeyShallowDiff initialVals valsChanged mkChild = do

139139--TODO: Something better than Dynamic t (Map k v) - we want something

140140--where the Events carry diffs, not the whole value

141141-- | Create a dynamically-changing set of Event-valued widgets. This

142−-- is like listWithKey, specialized for widgets returning (Event t

143−-- a). listWithKey would return 'Dynamic t (Map k (Event t a))' in

144−-- this scenario, but listViewWithKey flattens this to 'Event t (Map

145−-- k a)' via 'switch'.

142+-- is like 'listWithKey', specialized for widgets returning @/Event t a/@.

143+-- 'listWithKey' would return @/Dynamic t (Map k (Event t a))/@ in

144+-- this scenario, but 'listViewWithKey' flattens this to

145+-- @/Event t (Map k a)/@ via 'switch'.

146146listViewWithKey

147147 :: (Ord k, Adjustable t m, PostBuild t m, MonadHold t m, MonadFix m)

148148 => Dynamic t (Map k v)

src/Reflex/Dynamic.hs+17−17

@@ -58,6 +58,7 @@ module Reflex.Dynamic

5858 , Demux

5959 , demux

6060 , demuxed

61+ -- * Miscellaneous

6162 -- Things that probably aren't very useful:

6263 , HList (..)

6364 , FHList (..)

@@ -67,7 +68,7 @@ module Reflex.Dynamic

6768 , AllAreFunctors (..)

6869 , HListPtr (..)

6970 , distributeFHListOverDynPure

70− -- Unsafe

71+ -- * Unsafe

7172 , unsafeDynamic

7273 -- * Deprecated functions

7374 , apDyn

@@ -130,7 +131,7 @@ holdUniqDyn = holdUniqDynBy (==)

130131holdUniqDynBy :: (Reflex t, MonadHold t m, MonadFix m) => (a -> a -> Bool) -> Dynamic t a -> m (Dynamic t a)

131132holdUniqDynBy eq = scanDynMaybe id (\new old -> if new `eq` old then Nothing else Just new)

132133

133−-- | Dynamic Maybe that can only update from Nothing to Just or Just to Just (i.e., cannot revert to Nothing)

134+-- | @/Dynamic Maybe/@ that can only update from @/Nothing/@ to @/Just/@ or @/Just/@ to @/Just/@ (i.e., cannot revert to @/Nothing/@)

134135improvingMaybe :: (Reflex t, MonadHold t m, MonadFix m) => Dynamic t (Maybe a) -> m (Dynamic t (Maybe a))

135136improvingMaybe = scanDynMaybe id (\new _ -> if isJust new then Just new else Nothing)

136137

@@ -195,9 +196,9 @@ switchDyn :: forall t a. Reflex t => Dynamic t (Event t a) -> Event t a

195196switchDyn d = switch (current d)

196197

197198-- | Switches to the new 'Event' whenever it receives one. Switching occurs

198−-- *before* the inner 'Event' fires - so if the 'Dynamic' changes and both the

199+-- __before__ the inner 'Event' fires - so if the 'Dynamic' changes and both the

199200-- old and new inner Events fire simultaneously, the output will fire with the

200−-- value of the *new* 'Event'.

201+-- value of the __new__ 'Event'.

201202--

202203-- Prefer 'switchDyn' to this where possible. The timing requirements that

203204-- switching before imposes are likely to bring down your app unless you are

@@ -238,7 +239,7 @@ joinDynThroughMap :: forall t k a. (Reflex t, Ord k) => Dynamic t (Map k (Dynami

238239joinDynThroughMap = joinDyn . fmap distributeMapOverDynPure

239240

240241-- | Print the value of the 'Dynamic' when it is first read and on each

241−-- subsequent change that is observed (as traceEvent), prefixed with the

242+-- subsequent change that is observed (as 'traceEvent'), prefixed with the

242243-- provided string. This should /only/ be used for debugging.

243244--

244245-- Note: Just like Debug.Trace.trace, the value will only be shown if something

@@ -248,7 +249,7 @@ traceDyn s = traceDynWith $ \x -> s <> ": " <> show x

248249

249250-- | Print the result of applying the provided function to the value

250251-- of the 'Dynamic' when it is first read and on each subsequent change

251−-- that is observed (as traceEvent). This should /only/ be used for

252+-- that is observed (as 'traceEvent'). This should /only/ be used for

252253-- debugging.

253254--

254255-- Note: Just like Debug.Trace.trace, the value will only be shown if something

@@ -264,27 +265,27 @@ traceDynWith f d =

264265-- | Replace the value of the 'Event' with the current value of the 'Dynamic'

265266-- each time the 'Event' occurs.

266267--

267−-- Note: `tagPromptlyDyn d e` differs from `tag (current d) e` in the case that `e` is firing

268−-- at the same time that `d` is changing. With `tagPromptlyDyn d e`, the *new* value of `d`

269−-- will replace the value of `e`, whereas with `tag (current d) e`, the *old* value

268+-- Note: @/tagPromptlyDyn d e/@ differs from @/tag (current d) e/@ in the case that @/e/@ is firing

269+-- at the same time that @/d/@ is changing. With @/tagPromptlyDyn d e/@, the __new__ value of @/d/@

270+-- will replace the value of @/e/@, whereas with @/tag (current d) e/@, the __old__ value

270271-- will be used, since the 'Behavior' won't be updated until the end of the frame.

271272-- Additionally, this means that the output 'Event' may not be used to directly change

272−-- the input 'Dynamic', because that would mean its value depends on itself. When creating

273−-- cyclic data flows, generally `tag (current d) e` is preferred.

273+-- the input 'Dynamic', because that would mean its value depends on itself. __When creating__

274+-- __cyclic data flows, generally @/tag (current d) e/@ is preferred.__

274275tagPromptlyDyn :: Reflex t => Dynamic t a -> Event t b -> Event t a

275276tagPromptlyDyn = attachPromptlyDynWith const

276277

277278-- | Attach the current value of the 'Dynamic' to the value of the

278279-- 'Event' each time it occurs.

279280--

280−-- Note: `attachPromptlyDyn d` is not the same as `attach (current d)`. See 'tagPromptlyDyn' for details.

281+-- Note: @/attachPromptlyDyn d/@ is not the same as @/attach (current d)/@. See 'tagPromptlyDyn' for details.

281282attachPromptlyDyn :: Reflex t => Dynamic t a -> Event t b -> Event t (a, b)

282283attachPromptlyDyn = attachPromptlyDynWith (,)

283284

284285-- | Combine the current value of the 'Dynamic' with the value of the

285286-- 'Event' each time it occurs.

286287--

287−-- Note: `attachPromptlyDynWith f d` is not the same as `attachWith f (current d)`. See 'tagPromptlyDyn' for details.

288+-- Note: @/attachPromptlyDynWith f d/@ is not the same as @/attachWith f (current d)/@. See 'tagPromptlyDyn' for details.

288289attachPromptlyDynWith :: Reflex t => (a -> b -> c) -> Dynamic t a -> Event t b -> Event t c

289290attachPromptlyDynWith f = attachPromptlyDynWithMaybe $ \a b -> Just $ f a b

290291

@@ -292,8 +293,7 @@ attachPromptlyDynWith f = attachPromptlyDynWithMaybe $ \a b -> Just $ f a b

292293-- current value of the 'Dynamic' value and possibly filtering if the combining

293294-- function returns 'Nothing'.

294295--

295−-- Note: `attachPromptlyDynWithMaybe f d` is not the same as `attachWithMaybe f

296−-- (current d)`. See 'tagPromptlyDyn' for details.

296+-- Note: @/attachPromptlyDynWithMaybe f d/@ is not the same as @/attachWithMaybe f (current d)/@. See 'tagPromptlyDyn' for details.

297297attachPromptlyDynWithMaybe :: Reflex t => (a -> b -> Maybe c) -> Dynamic t a -> Event t b -> Event t c

298298attachPromptlyDynWithMaybe f d e =

299299 let e' = attach (current d) e

@@ -302,8 +302,8 @@ attachPromptlyDynWithMaybe f d e =

302302 These (_, b) a -> f a b -- Both events are firing, so use the newer value

303303 That _ -> Nothing -- The tagging event isn't firing, so don't fire

304304

305−-- | Factor a @Dynamic t (Maybe a)@ into a @Dynamic t (Maybe (Dynamic t a))@,

306−-- such that the outer 'Dynamic' is updated only when the 'Maybe''s constructor

305+-- | Factor a @/Dynamic t (Maybe a)/@ into a @/Dynamic t (Maybe (Dynamic t a))/@,

306+-- such that the outer 'Dynamic' is updated only when the "Maybe"'s constructor

307307-- chages from 'Nothing' to 'Just' or vice-versa. Whenever the constructor

308308-- becomes 'Just', an inner 'Dynamic' will be provided, whose value will track

309309-- the 'a' inside the 'Just'; when the constructor becomes 'Nothing', the

src/Reflex/Pure.hs+4−4

@@ -43,12 +43,12 @@ import Data.Type.Coercion

4343import Reflex.Class

4444

4545-- | A completely pure-functional 'Reflex' timeline, identifying moments in time

46−-- with the type @t@.

46+-- with the type @/t/@.

4747data Pure t

4848

49−-- | The Enum instance of t must be dense: for all x :: t, there must not exist

50−-- any y :: t such that pred x < y < x. The HasTrie instance will be used

51−-- exclusively to memoize functions of t, not for any of its other capabilities.

49+-- | The 'Enum' instance of @/t/@ must be dense: for all @/x :: t/@, there must not exist

50+-- any @/y :: t/@ such that @/'pred' x < y < x/@. The 'HasTrie' instance will be used

51+-- exclusively to memoize functions of @/t/@, not for any of its other capabilities.

5252instance (Enum t, HasTrie t, Ord t) => Reflex (Pure t) where

5353

5454 newtype Behavior (Pure t) a = Behavior { unBehavior :: t -> a }