[#73] Add 100% Haddock coverage + more examples (#155)

* [#73] Add 100% Haddock coverage + more examples

* [#73] Fix documentation typos and wording

CHANGES.md

@@ -1,6 +1,8 @@
-1.2.0
+1.1.1
 =====
 
+* [#73](https://github.com/serokell/universum/issues/73):
+  Add more examples to docs and fix warnings where possible.
 * Move reexport of `NonEmpty` to `Universum.List` module.
 
 1.1.0

README.md

@@ -348,9 +348,3 @@ Projects that use Universum [↑](#structure-of-this-tutorial)
 - [importify](https://github.com/serokell/importify)
 - [log-warper](https://github.com/serokell/log-warper)
 - [orgstat](https://github.com/volhovm/orgstat)
-
-License
--------
-
-Released under the MIT License.
-Copyright (c) 2016, Stephen Diehl, 2016-2017, Serokell

src/Universum/Bool/Guard.hs

@@ -1,3 +1,5 @@
+-- | This module contains monadic predicates.
+
 module Universum.Bool.Guard
        ( guardM
        , ifM

src/Universum/Bool/Reexport.hs

@@ -1,3 +1,5 @@
+-- | This module reexports functions to work with 'Bool' type.
+
 module Universum.Bool.Reexport
        ( module Control.Monad
        , module Data.Bool

src/Universum/Container/Class.hs

@@ -42,7 +42,7 @@ module Universum.Container.Class
        ) where
 
 import Data.Coerce (Coercible, coerce)
-import Prelude hiding (all, and, any, elem, foldMap, foldl, foldr, mapM_, notElem, null, or,
+import Prelude hiding (all, and, any, elem, foldMap, foldl, foldr, mapM_, notElem, null, or, print,
                 product, sequence_, sum)
 
 import Universum.Applicative (Alternative (..), Const, ZipList, pass)
@@ -86,6 +86,9 @@ import qualified Data.Vector.Storable as VS
 import qualified Data.Vector.Unboxed as VU
 
 -- $setup
+-- >>> import Universum.Base (even)
+-- >>> import Universum.Bool (when)
+-- >>> import Universum.Print (print, putTextLn)
 -- >>> import Universum.String (Text)
 -- >>> import qualified Data.HashMap.Strict as HashMap
 
@@ -604,45 +607,86 @@ sum = foldl' (+) 0
 product :: (Container t, Num (Element t)) => t -> Element t
 product = foldl' (*) 1
 
--- | Constrained to 'Container' version of 'Data.Foldable.traverse_'.
+{- | Constrained to 'Container' version of 'Data.Foldable.traverse_'.
+
+>>> traverse_ putTextLn ["foo", "bar"]
+foo
+bar
+
+-}
 traverse_
     :: (Container t, Applicative f)
     => (Element t -> f b) -> t -> f ()
 traverse_ f = foldr ((*>) . f) pass
 
--- | Constrained to 'Container' version of 'Data.Foldable.for_'.
+{- | Constrained to 'Container' version of 'Data.Foldable.for_'.
+
+>>> for_ [1 .. 5 :: Int] $ \i -> when (even i) (print i)
+2
+4
+
+-}
 for_
     :: (Container t, Applicative f)
     => t -> (Element t -> f b) -> f ()
 for_ = flip traverse_
 {-# INLINE for_ #-}
 
--- | Constrained to 'Container' version of 'Data.Foldable.mapM_'.
+{- | Constrained to 'Container' version of 'Data.Foldable.mapM_'.
+
+>>> mapM_ print [True, False]
+True
+False
+
+-}
 mapM_
     :: (Container t, Monad m)
     => (Element t -> m b) -> t -> m ()
 mapM_ f= foldr ((>>) . f) pass
 
--- | Constrained to 'Container' version of 'Data.Foldable.forM_'.
+{- | Constrained to 'Container' version of 'Data.Foldable.forM_'.
+
+>>> forM_ [True, False] print
+True
+False
+
+-}
 forM_
     :: (Container t, Monad m)
     => t -> (Element t -> m b) -> m ()
 forM_ = flip mapM_
 {-# INLINE forM_ #-}
 
--- | Constrained to 'Container' version of 'Data.Foldable.sequenceA_'.
+{- | Constrained to 'Container' version of 'Data.Foldable.sequenceA_'.
+
+>>> sequenceA_ [putTextLn "foo", print True]
+foo
+True
+
+-}
 sequenceA_
     :: (Container t, Applicative f, Element t ~ f a)
     => t -> f ()
 sequenceA_ = foldr (*>) pass
 
--- | Constrained to 'Container' version of 'Data.Foldable.sequence_'.
+{- | Constrained to 'Container' version of 'Data.Foldable.sequence_'.
+
+>>> sequence_ [putTextLn "foo", print True]
+foo
+True
+
+-}
 sequence_
     :: (Container t, Monad m, Element t ~ m a)
     => t -> m ()
 sequence_ = foldr (>>) pass
 
--- | Constrained to 'Container' version of 'Data.Foldable.asum'.
+{- | Constrained to 'Container' version of 'Data.Foldable.asum'.
+
+>>> asum [Nothing, Just [False, True], Nothing, Just [True]]
+Just [False,True]
+
+-}
 asum
     :: (Container t, Alternative f, Element t ~ f a)
     => t -> f a

src/Universum/DeepSeq.hs

@@ -1,3 +1,7 @@
+-- | This module contains useful functions to evaluate expressions to weak-head
+-- normal form or just normal form. Useful to force traces or @error@ inside
+-- monadic computation or to remove space leaks.
+
 module Universum.DeepSeq
        ( module Control.DeepSeq
        , evaluateNF

src/Universum/Function.hs

@@ -1,3 +1,5 @@
+-- | This module reexports very basic and primitive functions and function combinators.
+
 module Universum.Function
        ( module Data.Function
        , identity

src/Universum/Functor/Fmap.hs

@@ -1,5 +1,7 @@
 {-# LANGUAGE Safe #-}
 
+-- | This module contains useful functions to work with 'Functor' type class.
+
 module Universum.Functor.Fmap
        ( map
        , (<<$>>)
@@ -8,7 +10,21 @@ module Universum.Functor.Fmap
 import Universum.Function ((.))
 import Universum.Functor.Reexport (Functor (..))
 
--- | 'Prelude.map' generalized to 'Functor'.
+-- $setup
+-- >>> import Universum.Base (negate)
+-- >>> import Universum.Bool (Bool (..), not)
+-- >>> import Universum.Lifted (getLine)
+-- >>> import Universum.Monad (Maybe (..))
+-- >>> import Universum.String (toString)
+
+{- | 'Prelude.map' generalized to 'Functor'.
+
+>>> map not (Just True)
+Just False
+>>> map not [True,False,True,True]
+[False,True,False,False]
+
+-}
 map :: Functor f => (a -> b) -> f a -> f b
 map = fmap
 

src/Universum/Functor/Reexport.hs

@@ -1,5 +1,7 @@
 {-# LANGUAGE Safe #-}
 
+-- | This module reexports functionality regarding 'Functor' type class.
+
 module Universum.Functor.Reexport
        ( module Control.Arrow
        , module Data.Bifunctor

src/Universum/Lifted/ST.hs

@@ -1,3 +1,5 @@
+-- | This module contains lifted version of 'XIO.stToIO' function.
+
 module Universum.Lifted.ST
        ( stToIO
        ) where

src/Universum/List/Reexport.hs

@@ -1,6 +1,8 @@
 {-# LANGUAGE CPP         #-}
 {-# LANGUAGE Trustworthy #-}
 
+-- | This module reexports functinons to work with list, 'NonEmpty' and String types.
+
 module Universum.List.Reexport
        ( module Data.List
 

src/Universum/List/Safe.hs

@@ -1,6 +1,8 @@
 {-# LANGUAGE CPP         #-}
 {-# LANGUAGE Trustworthy #-}
 
+-- | This module contains safe functions to work with list type (mostly with 'NonEmpty').
+
 module Universum.List.Safe
        ( list
        , uncons
@@ -22,9 +24,10 @@ import Universum.Monad (Maybe (..))
 -- $setup
 -- >>> import Universum.Applicative (pure)
 -- >>> import Universum.Base ((==), even)
--- >>> import Universum.Bool (Bool (..))
+-- >>> import Universum.Bool (Bool (..), not)
 -- >>> import Universum.Container (length)
 -- >>> import Universum.Function (($))
+-- >>> import Universum.Print (print)
 
 -- | Returns default list if given list is empty.
 -- Otherwise applies given function to every element.
@@ -51,7 +54,13 @@ uncons []     = Nothing
 uncons (x:xs) = Just (x, xs)
 
 #if ( __GLASGOW_HASKELL__ >= 800 )
--- | Performs given action over 'NonEmpty' list if given list is non empty.
+{- | Performs given action over 'NonEmpty' list if given list is non empty.
+
+>>> whenNotNull [] $ \(b :| _) -> print (not b)
+>>> whenNotNull [False,True] $ \(b :| _) -> print (not b)
+True
+
+-}
 whenNotNull :: Applicative f => [a] -> (NonEmpty a -> f ()) -> f ()
 whenNotNull []     _ = pass
 whenNotNull (x:xs) f = f (x :| xs)

src/Universum/Monad/Container.hs

@@ -1,5 +1,8 @@
 {-# LANGUAGE TypeFamilies #-}
 
+-- | This module exports functions which allow to process instances of
+-- 'Container' type class in monadic way.
+
 module Universum.Monad.Container
        ( concatMapM
        , concatForM

src/Universum/Monad/Maybe.hs

@@ -17,9 +17,9 @@ import Universum.Monad.Reexport (fromMaybe)
 import Universum.Monad.Reexport (Maybe (..), Monad (..))
 
 -- $setup
--- >>> import Universum.Bool (Bool (..))
+-- >>> import Universum.Bool (Bool (..), not)
 -- >>> import Universum.Function (($))
--- >>> import Universum.Print (putTextLn)
+-- >>> import Universum.Print (putTextLn, print)
 -- >>> import Universum.String (readMaybe)
 
 {- | Similar to 'fromMaybe' but with flipped arguments.
@@ -36,9 +36,15 @@ infixr 0 ?:
 mA ?: b = fromMaybe b mA
 {-# INLINE (?:) #-}
 
--- | Specialized version of 'for_' for 'Maybe'. It's used for code readability.
--- Also helps to avoid space leaks:
--- <http://www.snoyman.com/blog/2017/01/foldable-mapm-maybe-and-recursive-functions Foldable.mapM_ space leak>.
+{- | Specialized version of 'for_' for 'Maybe'. It's used for code readability.
+Also helps to avoid space leaks:
+<http://www.snoyman.com/blog/2017/01/foldable-mapm-maybe-and-recursive-functions Foldable.mapM_ space leak>.
+
+>>> whenJust Nothing $ \b -> print (not b)
+>>> whenJust (Just True) $ \b -> print (not b)
+False
+
+-}
 whenJust :: Applicative f => Maybe a -> (a -> f ()) -> f ()
 whenJust (Just x) f = f x
 whenJust Nothing _  = pass

src/Universum/Monad/Reexport.hs

@@ -1,6 +1,8 @@
 {-# LANGUAGE CPP         #-}
 {-# LANGUAGE Trustworthy #-}
 
+-- | This module reexports functions to work with monads.
+
 module Universum.Monad.Reexport
        ( -- * Reexport transformers
          module Control.Monad.Except

src/Universum/Monoid.hs

@@ -1,5 +1,7 @@
 {-# LANGUAGE CPP #-}
 
+-- | This module reexports functions to work with monoids plus adds extra useful functions.
+
 module Universum.Monoid
        ( module Data.Monoid
 #if ( __GLASGOW_HASKELL__ >= 800 )

src/Universum/String/Conversion.hs

@@ -4,6 +4,12 @@
 {-# LANGUAGE MultiParamTypeClasses #-}
 {-# LANGUAGE TypeSynonymInstances  #-}
 
+-- | This module implements type class which allow to have conversion to and
+-- from 'Text', 'String' and 'ByteString' types (including both strict and lazy
+-- versions). Usually you need to export 'Text' modules qualified and use
+-- 'T.pack' \/ 'T.unpack' functions to convert to\/from 'Text'. Now you can
+-- just use 'toText' \/ 'toString' functions.
+
 module Universum.String.Conversion
        ( -- * Convenient type aliases
          LText

src/Universum/String/Reexport.hs

@@ -1,3 +1,5 @@
+-- | This module reexports functions to work with 'Text' and 'ByteString' types.
+
 module Universum.String.Reexport
        ( -- * String
          module Data.String

src/Universum/VarArg.hs

@@ -17,6 +17,7 @@ module Universum.VarArg
 -- >>> import Prelude (show)
 -- >>> import Data.List (zip5)
 
+-- | This type class allows to implement variadic composition operator.
 class SuperComposition a b c | a b -> c where
     -- | Allows to apply function to result of another function with multiple
     -- arguments.

stack.yaml

@@ -1,4 +1,4 @@
-resolver: lts-10.5
+resolver: lts-10.7
 
 nix:
   shell-file: shell.nix

universum.cabal

@@ -1,5 +1,5 @@
 name:                universum
-version:             1.1.0
+version:             1.1.1
 synopsis:            Custom prelude used in Serokell
 description:         See README.md file for more details.
 homepage:            https://github.com/serokell/universum
@@ -126,7 +126,7 @@ test-suite universum-doctest
 benchmark universum-benchmark
   type:                exitcode-stdio-1.0
   default-language:    Haskell2010
-  ghc-options:         -Wall -O2 -threaded -rtsopts -with-rtsopts=-N
+  ghc-options:         -Wall -threaded -rtsopts -with-rtsopts=-N
   hs-source-dirs:      benchmark
   main-is:             Main.hs
   build-depends:       base < 5