git.iko.soy/streamly
on master help sign in
Make StreamK, StreamD and Prelude haddock consistent
c7b46adHarendra Kumar
CONTRIBUTING.md+6
compare with master
unifiedsplit
@@ -9,6 +9,12 @@ we will appreciate if you provide as much detail as possible to reproduce or
9understand the problem, but nevertheless you are encouraged to open an issue
9understand the problem, but nevertheless you are encouraged to open an issue
10for any problem that you may encounter.
10for any problem that you may encounter.
11
11
12+## Developer documentation
13+
14+Build haddock with the `dev` flag to see the whole documentation and module
15+structure. For example,
16+`stack haddock --flag "streamly:dev" --no-haddock-deps`.
17+
12## Pull Requests (PR)
18## Pull Requests (PR)
13
19
14Please feel free to [send a pull
20Please feel free to [send a pull
src/Streamly/Prelude.hs+13−13
@@ -46,15 +46,16 @@
46module Streamly.Prelude
46module Streamly.Prelude
47 (
47 (
48 -- * Construction
48 -- * Construction
49− -- | Primitives to construct or inspect a stream.
49+ -- | Primitives to construct a stream.
50 K.nil
50 K.nil
51− , K.yield
52− , K.yieldM
53 , K.cons
51 , K.cons
54 , (K..:)
52 , (K..:)
55 , consM
53 , consM
56 , (|:)
54 , (|:)
57
55
56+ -- * Deconstruction
57+ , uncons
58+
58 -- * Generation by Unfolding
59 -- * Generation by Unfolding
59 , unfoldr
60 , unfoldr
60 , unfoldrM
61 , unfoldrM
@@ -62,6 +63,8 @@ module Streamly.Prelude
62 -- * Special Generation
63 -- * Special Generation
63 -- | Generate a monadic stream from an input structure, a seed or a
64 -- | Generate a monadic stream from an input structure, a seed or a
64 -- generation function.
65 -- generation function.
66+ , K.yield
67+ , K.yieldM
65 , replicateM
68 , replicateM
66 , K.repeat
69 , K.repeat
67 , repeatM
70 , repeatM
@@ -72,9 +75,6 @@ module Streamly.Prelude
72 , K.fromFoldable
75 , K.fromFoldable
73 , fromFoldableM
76 , fromFoldableM
74
77
75− -- * Deconstruction
76− , uncons
77−
78 -- * Elimination by Folding
78 -- * Elimination by Folding
79 -- ** General Folds
79 -- ** General Folds
80 , foldr
80 , foldr
@@ -105,6 +105,13 @@ module Streamly.Prelude
105 , scanl'
105 , scanl'
106 , scanx
106 , scanx
107
107
108+ -- * Mapping
109+ , Serial.map
110+ , mapM
111+ , mapMaybe
112+ , mapMaybeM
113+ , sequence
114+
108 -- * Filtering
115 -- * Filtering
109 , filter
116 , filter
110 , take
117 , take
@@ -115,13 +122,6 @@ module Streamly.Prelude
115 -- * Reordering
122 -- * Reordering
116 , reverse
123 , reverse
117
124
118− -- * Mapping
119− , Serial.map
120− , mapM
121− , mapMaybe
122− , mapMaybeM
123− , sequence
124−
125 -- * Zipping
125 -- * Zipping
126 , zipWith
126 , zipWith
127 , zipWithM
127 , zipWithM
src/Streamly/Streams/StreamD.hs+12−7
@@ -26,7 +26,9 @@
26-- to INLINE and fuse direct style better, providing better performance than
26-- to INLINE and fuse direct style better, providing better performance than
27-- CPS implementation.
27-- CPS implementation.
28--
28--
29+-- @
29-- import qualified Streamly.Streams.StreamD as D
30-- import qualified Streamly.Streams.StreamD as D
31+-- @
30--
32--
31module Streamly.Streams.StreamD
33module Streamly.Streams.StreamD
32 (
34 (
@@ -35,23 +37,26 @@ module Streamly.Streams.StreamD
35 , Stream (..)
37 , Stream (..)
36
38
37 -- * Construction
39 -- * Construction
40+ -- | Direct style stream does not support construction by adding more
41+ -- elements to an existing stream.
38 , nil
42 , nil
39− , yield
43+
40− , yieldM
44+ -- * Deconstruction
45+ , uncons
41
46
42 -- * Generation by Unfolding
47 -- * Generation by Unfolding
43 , unfoldr
48 , unfoldr
44 , unfoldrM
49 , unfoldrM
45
50
46 -- * Special Generation
51 -- * Special Generation
52+ -- | Direct style stream does not support @fromFoldable@.
53+ , yield
54+ , yieldM
47 , repeat
55 , repeat
48 , enumFromStepN
56 , enumFromStepN
49 , fromList
57 , fromList
50 , fromListM
58 , fromListM
51
59
52− -- * Deconstruction
53− , uncons
54−
55 -- * Elimination by Folding
60 -- * Elimination by Folding
56 -- ** General Folds
61 -- ** General Folds
57 , foldr
62 , foldr
@@ -86,8 +91,8 @@ import qualified Streamly.Streams.StreamK as K
86------------------------------------------------------------------------------
91------------------------------------------------------------------------------
87
92
88-- | A stream is a succession of 'Step's. A 'Yield' produces a single value and
93-- | A stream is a succession of 'Step's. A 'Yield' produces a single value and
89−-- the next state of the stream. Stop indicates there are no more values in the
94+-- the next state of the stream. 'Stop' indicates there are no more values in
90−-- stream.
95+-- the stream.
91data Step s a = Yield a s | Stop
96data Step s a = Yield a s | Stop
92
97
93instance Functor (Step s) where
98instance Functor (Step s) where
src/Streamly/Streams/StreamK.hs+18−10
@@ -24,7 +24,9 @@
24-- Continuation passing style (CPS) stream implementation. The symbol 'K' below
24-- Continuation passing style (CPS) stream implementation. The symbol 'K' below
25-- denotes a function as well as a Kontinuation.
25-- denotes a function as well as a Kontinuation.
26--
26--
27+-- @
27-- import qualified Streamly.Streams.StreamK as K
28-- import qualified Streamly.Streams.StreamK as K
29+-- @
28--
30--
29module Streamly.Streams.StreamK
31module Streamly.Streams.StreamK
30 (
32 (
@@ -38,8 +40,6 @@ module Streamly.Streams.StreamK
38 -- * Construction
40 -- * Construction
39 , mkStream
41 , mkStream
40 , nil
42 , nil
41− , yield
42− , yieldM
43 , cons
43 , cons
44 , (.:)
44 , (.:)
45
45
@@ -48,27 +48,33 @@ module Streamly.Streams.StreamK
48 , yieldK
48 , yieldK
49 , consK
49 , consK
50
50
51− -- * Generation
51+ -- * Generation by Unfolding
52 , unfoldr
52 , unfoldr
53 , unfoldrM
53 , unfoldrM
54+
55+ -- * Special Generation
56+ , yield
57+ , yieldM
54 , repeat
58 , repeat
55 , fromFoldable
59 , fromFoldable
56
60
57− -- * Elimination
61+ -- * Elimination by Folding
62+ -- ** General Folds
58 , foldStream
63 , foldStream
59 , foldr
64 , foldr
60 , foldrM
65 , foldrM
61− , foldx
62 , foldl'
66 , foldl'
63− , foldxM
64 , foldlM'
67 , foldlM'
68+ , foldx
69+ , foldxM
65
70
71+ -- ** Special Folds
66 , runStream
72 , runStream
67 , mapM_
73 , mapM_
68 , toList
74 , toList
69 , last
75 , last
70
76
71− -- * Transformation
77+ -- * Mapping
72 , map
78 , map
73 , mapM
79 , mapM
74
80
@@ -99,14 +105,16 @@ import Streamly.SVar
99-- The basic stream type
105-- The basic stream type
100------------------------------------------------------------------------------
106------------------------------------------------------------------------------
101
107
102−-- | The type 'Stream m a' represents a monadic stream of values of type 'a'
108+-- | The type @Stream m a@ represents a monadic stream of values of type 'a'
103-- constructed using actions in monad 'm'. It uses stop, singleton and yield
109-- constructed using actions in monad 'm'. It uses stop, singleton and yield
104-- continuations equivalent to the following direct style type:
110-- continuations equivalent to the following direct style type:
105--
111--
112+-- @
106-- data Stream m a = Stop | Singleton a | Yield a (Stream m a)
113-- data Stream m a = Stop | Singleton a | Yield a (Stream m a)
114+-- @
107--
115--
108−-- To facilitate parallel composition we maintain a local state in an SVar that
116+-- To facilitate parallel composition we maintain a local state in an 'SVar'
109−-- is shared across and is used for synchronization of the streams being
117+-- that is shared across and is used for synchronization of the streams being
110-- composed.
118-- composed.
111--
119--
112-- The singleton case can be expressed in terms of stop and yield but we have
120-- The singleton case can be expressed in terms of stop and yield but we have