[#54] Improve documentation (#57)

* [#54] Improve documentation

* Fix comments for documentation

CHANGELOG.md

@@ -13,6 +13,12 @@ Change log
   Also reexport `fromLeft` and `fromRight` from `base` where possible.
 * [#49](https://github.com/kowainik/relude/issues/49):
   Speed up and refactor property tests.
+* [#54](https://github.com/kowainik/relude/issues/54):
+  Improve documentation.
+  Add more examples to documentation and more tests.
+  Reexport `withReader` and `withReaderT`.
+  Remove `safeHead`.
+  Rename `Relude.List.Safe` to `Relude.List.NonEmpty`.
 
 0.1.1
 =====

LICENSE

@@ -1,5 +1,5 @@
 The MIT License (MIT)
-Copyright (c) 2016-2017, Stephen Diehl, 2017, Serokell, 2018, Kowainik
+Copyright (c) 2016, Stephen Diehl, 2016-2018, Serokell, 2018, Kowainik
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to

README.md

@@ -208,7 +208,11 @@ We also have `data Undefined = Undefined` (which, too, comes with warnings).
 
 ### Exceptions
 
-TODO: write about reexports, `Bug` and `Exc` pattern.
+`relude` reexports `Exception` type from the `base` package and introduces the
+`bug` function as an alternative to `error`. There's also a very convenient
+`Exc` pattern-synonym to handle exceptions of different types.
+
+See [`Relude.Exception`](src/Relude/Exception.hs) module for details.
 
 What's new? [↑](#structure-of-this-tutorial)
 --------------------------------------------

relude.cabal

@@ -93,8 +93,8 @@ library
                                Relude.Lifted.File
                                Relude.Lifted.IORef
                            Relude.List
+                               Relude.List.NonEmpty
                                Relude.List.Reexport
-                               Relude.List.Safe
                            Relude.Monad
                                Relude.Monad.Either
                                Relude.Monad.Maybe
@@ -116,7 +116,6 @@ library
                            Relude.Extra.Newtype
                            Relude.Unsafe
 
-
   ghc-options:         -Wall
                        -Wcompat
                        -Widentities

src/Relude.hs

@@ -1,15 +1,15 @@
 {-# LANGUAGE Trustworthy #-}
 
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
-{- | Main module that reexports all functionality allowed to use
+The main module that reexports all functionality. It's allowed to use it without
-without importing any other modules. Just add next lines to your
+importing any other modules. If you want to use @relude@ per-module basis then
-module to replace default 'Prelude' with better one.
+just add next lines to your module to replace default 'Prelude':
 
 @
 \{\-\# LANGUAGE NoImplicitPrelude \#\-\}
@@ -17,33 +17,47 @@ module to replace default 'Prelude' with better one.
 __import__ "Relude"
 @
 
-This documentation section contains description of internal module structure to
+Alternatively, you can replace @base@ package in your dependencies with
+@[base-noprelude](http://hackage.haskell.org/package/base-noprelude)@ and add
+the following 'Prelude' module to your package to use @relude@ by default in
+every module instead of 'Prelude':
+
+@
+__module__ Prelude (__module__ "Relude") __where__
+__import__ "Relude"
+@
+
+This documentation section contains the description of internal module structure to
 help navigate between modules, search for interesting functionalities and
-understand where you need to put your new changes.
+understand where you need to put your new changes (if you're a contributor).
 
 Functions and types are distributed across multiple modules and grouped by
-meaning or __theme__. Name of the module should give you hints regarding what
+meaning or __category__. Name of the module should give you hints regarding what
-this module contains. Some /themes/ contain a great amount of both reexported
+this module contains. Some /categories/ contain a significant amount of both reexported
-functions and functions of our own. To make it easier to understand these huge
+functions and functions of our own. To make it easier to understand these enormous
-chunks of functions, all reexported stuff is moved into separate module with
+chunks of functions, all reexported stuff is moved into the separate module with
-name @Relude.SomeTheme.Reexport@ and our own functions and types are in
+name @Relude.SomeCategory.Reexport@ and our own functions and types are in
-@Relude.SomeTheme.SomeName@. For example, see modules
+@Relude.SomeCategory.SomeName@. For example, see modules
-"Relude.Container.Class" and "Relude.Container.Reexport".
+"Relude.Foldable.Fold" and "Relude.Foldable.Reexport".
 
-Below is a short description of what you can find under different modules:
+Below is a short description of what you can find under different modules,
+imported by default from "Relude":
 
 * __"Relude.Applicative"__: reexports from "Control.Applicative" and some
   general-purpose applicative combinators.
 * __"Relude.Base"__: different general types and type classes from @base@
   package ('Int', 'Num', 'Generic', etc.) not exported by other modules.
 * __"Relude.Bool"__: 'Bool' data type with different predicates and combinators.
+* __"Relude.Container"__: 'One' typeclass for creating data structures from
+  singleton lement and reexports of types from packages @containers@ and
+  @unordered-containers@.
 * __"Relude.Debug"__: @trace@-like debugging functions with compile-time
-  warnings (so you don't forget to remove them)
+  warnings (so you don't forget to remove them).
 * __"Relude.DeepSeq"__: reexports from "Control.DeepSeq" module and
   functions to evaluate expressions to weak-head normal form or normal form.
-* __"Relude.Exception"__: reexports "Control.Exception.Safe" from
+* __"Relude.Exception"__: reexports "Control.Exception", introduces 'bug'
-  @safe-exceptions@ package, 'bug' as better 'error', 'Exc' pattern synonym for
+  function as better 'error' and 'Exc' pattern synonym for convenient
-  convenient pattern-matching on exceptions.
+  pattern-matching on exceptions.
 * __"Relude.Foldable"__: reexports functions for 'Foldable' and 'Traversable'.
 * __"Relude.Function"__: almost everything from "Data.Function" module.
 * __"Relude.Functor"__: reexports from "Data.Functor", "Data.Bifunctor",
@@ -52,14 +66,28 @@ Below is a short description of what you can find under different modules:
   files, 'IORef's, 'MVar's, etc.
 * __"Relude.List"__: big chunk of "Data.List", 'NonEmpty' type and
   functions for this type ('head', 'tail', 'last', 'init').
-* __"Relude.Monad"__: monad transormers, combinators for 'Maybe' and 'Either'.
+* __"Relude.Monad"__: reexports from "Data.Maybe" and "Data.Either" modules,
+  monad transormers, various combinators.
 * __"Relude.Monoid"__: reexports from "Data.Monoid" and "Data.Semigroup".
 * __"Relude.Nub"__: better versions of @nub@ function for list.
 * __"Relude.Print"__: polymorphic 'putStrLn' function and functions to print 'Text'.
 * __"Relude.String"__: reexports from @text@ and @bytestring@ packages with
     conversion functions between different textual types.
-* __"Relude.Unsafe"__: unsafe functions (produce 'error').
+
-  Not exported by "Relude" module by default.
+And these modules are not exported by default, but you can easily bring them to
+every module in your package by modifying your "Prelude" file:
+
+* __"Relude.Extra.Bifunctor"__: additional combinators for 'Bifunctor'.
+* __"Relude.Extra.CallStack"__: useful functions to extract information from
+  'CallStack'.
+* __"Relude.Extra.Enum"__: extra utilities for types that implement 'Bounded'
+  and 'Enum' constraints.
+* __"Relude.Extra.Group"__: grouping functions, polymorphic on return @Map@ type.
+* __"Relude.Extra.Map"__: typeclass for @Map@-like data structures.
+* __"Relude.Extra.Newtype"__: generic functions that automatically work for any
+  @newtype@.
+* __"Relude.Unsafe"__: unsafe partial functions (produce 'error') for lists and
+  'Maybe'.
 -}
 
 module Relude

src/Relude/Applicative.hs

@@ -1,15 +1,16 @@
 {-# LANGUAGE Safe #-}
 
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
--- | Convenient utils to work with 'Applicative'. There were more functions in this module
+Convenient utils to work with 'Applicative'. There were more functions in this module
--- (see <https://www.stackage.org/haddock/lts-8.9/protolude-0.1.10/Applicative.html protolude version>)
+(see <https://www.stackage.org/haddock/lts-8.9/protolude-0.1.10/Applicative.html protolude version>)
--- but only convenient ans most used are left.
+but only convenient ans most used are left.
+-}
 
 module Relude.Applicative
        ( module Control.Applicative

src/Relude/Base.hs

@@ -1,16 +1,16 @@
-{-# LANGUAGE BangPatterns #-}
+{-# LANGUAGE CPP    #-}
-{-# LANGUAGE CPP          #-}
+{-# LANGUAGE Unsafe #-}
-{-# LANGUAGE Unsafe       #-}
 
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
--- | Reexports from @GHC.*@ modules of <https://www.stackage.org/lts-8.9/package/base-4.9.1.0 base>
+Reexports from @Data.*@ and @GHC.*@ modules of
--- package.
+<https://www.stackage.org/lts-8.9/package/base-4.9.1.0 base> package.
+-}
 
 module Relude.Base
        ( -- * Base types
@@ -51,8 +51,6 @@ module Relude.Base
        , module GHC.OverloadedLabels
        , module GHC.ExecutionStack
        , module GHC.Stack
-
-       , ($!)
        ) where
 
 -- Base types
@@ -76,12 +74,13 @@ import Data.Proxy (Proxy (..))
 import Data.Typeable (Typeable)
 import Data.Void (Void, absurd, vacuous)
 
-import GHC.Base (String, asTypeOf, maxInt, minInt, ord, seq)
+import GHC.Base (String, asTypeOf, maxInt, minInt, ord, seq, ($!))
 import GHC.Enum (Bounded (..), Enum (..), boundedEnumFrom, boundedEnumFromThen)
 import GHC.Float (Double (..), Float (..), Floating (acos, acosh, asin, asinh, atan, atanh, cos, cosh, exp, logBase, pi, sin, sinh, sqrt, tan, tanh, (**)))
 import GHC.Generics (Generic)
 import GHC.Num (Integer, Num (..), subtract)
-import GHC.Real hiding (showSigned, (%))
+import GHC.Real (Fractional (..), Integral (..), Ratio, Rational, Real (..), RealFrac (..),
+                 denominator, even, fromIntegral, gcd, lcm, numerator, odd, realToFrac, (^), (^^))
 import GHC.Show (Show)
 
 #if MIN_VERSION_base(4,10,0)
@@ -94,20 +93,3 @@ import GHC.ExecutionStack (getStackTrace, showStackTrace)
 import GHC.OverloadedLabels (IsLabel (..))
 import GHC.Stack (CallStack, HasCallStack, callStack, currentCallStack, getCallStack,
                   prettyCallStack, prettySrcLoc, withFrozenCallStack)
-
--- $setup
--- >>> import Relude.Function (const, ($))
-
--- | Stricter version of 'Data.Function.$' operator.
--- Default Prelude defines this at the toplevel module, so we do as well.
---
--- >>> const 3 $ Prelude.undefined
--- 3
--- >>> const 3 $! Prelude.undefined
--- *** Exception: Prelude.undefined
--- CallStack (from HasCallStack):
---   error, called at libraries/base/GHC/Err.hs:79:14 in base:GHC.Err
--- ...
-($!) :: (a -> b) -> a -> b
-f $! x = let !vx = x in f vx
-infixr 0 $!

src/Relude/Bool.hs

@@ -1,7 +1,15 @@
 {-# LANGUAGE Safe #-}
 
--- | Convenient commonly used and very helpful functions to work with
+{- |
--- 'Bool' and also with monads.
+Copyright: (c) 2016 Stephen Diehl
+           (c) 20016-2018 Serokell
+           (c) 2018 Kowainik
+License:    MIT
+Maintainer: Kowainik <xrom.xkov@gmail.com>
+
+Convenient commonly used and very helpful functions to work with 'Bool' and also
+with monads.
+-}
 
 module Relude.Bool
        ( module Relude.Bool.Guard

src/Relude/Bool/Guard.hs

@@ -1,11 +1,12 @@
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
--- | This module contains monadic predicates.
+Monadic boolean combinators.
+-}
 
 module Relude.Bool.Guard
        ( guardM

src/Relude/Bool/Reexport.hs

@@ -1,11 +1,12 @@
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
--- | This module reexports functions to work with 'Bool' type.
+Reexports functions to work with 'Bool' type.
+-}
 
 module Relude.Bool.Reexport
        ( module Control.Monad

src/Relude/Container.hs

@@ -1,11 +1,12 @@
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
--- | This module exports all container-related stuff.
+This module exports all container-related stuff.
+-}
 
 module Relude.Container
        ( module Relude.Container.One

src/Relude/Container/One.hs

@@ -2,14 +2,14 @@
 {-# LANGUAGE FlexibleInstances #-}
 {-# LANGUAGE TypeFamilies      #-}
 
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
-{- | Typeclass for creating structures from singleton element.
+Typeclass for creating structures from singleton element.
 -}
 
 module Relude.Container.One

src/Relude/Container/Reexport.hs

@@ -1,11 +1,13 @@
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
--- | This module reexports all container related stuff from 'Prelude'.
+Reexports all container-related stuff from @base@, @containers@ and
+@unordered-containers@ packages.
+-}
 
 module Relude.Container.Reexport
        ( module Data.Hashable

src/Relude/Debug.hs

@@ -10,16 +10,17 @@
 {-# LANGUAGE TypeInType         #-}
 #endif
 
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
--- | Functions for debugging. If you left these functions in your code
+Functions for debugging. If you left these functions in your code then a warning
--- then warning is generated to remind you about left usages. Also some
+is generated to remind you about left usages. Also some functions (and data
--- functions (and data types) are convenient for prototyping.
+types) are convenient for prototyping.
+-}
 
 module Relude.Debug
        ( Undefined (..)
@@ -33,18 +34,15 @@ module Relude.Debug
        , undefined
        ) where
 
-import Control.Monad (Monad, return)
 import Data.Data (Data)
-import Data.Text (Text, unpack)
-import Data.Typeable (Typeable)
 import GHC.Exts (RuntimeRep, TYPE)
-import GHC.Generics (Generic)
 import System.IO.Unsafe (unsafePerformIO)
 
-import Relude.Base (HasCallStack)
-
 import Relude.Applicative (pass)
+import Relude.Base (Generic, HasCallStack, Typeable)
+import Relude.Monad.Reexport (Monad (..))
 import Relude.Print (Print, putStrLn)
+import Relude.String (Text, toString)
 
 import qualified Prelude as P
 
@@ -58,7 +56,7 @@ trace string expr = unsafePerformIO (do
 -- | 'P.error' that takes 'Text' as an argument.
 error :: forall (r :: RuntimeRep) . forall (a :: TYPE r) . HasCallStack
       => Text -> a
-error s = P.error (unpack s)
+error s = P.error (toString s)
 
 -- | Version of 'Debug.Trace.traceShow' that leaves warning.
 {-# WARNING traceShow "'traceShow' remains in code" #-}
@@ -78,7 +76,7 @@ traceShowM a = trace (P.show a) pass
 -- | Version of 'Debug.Trace.traceM' that leaves warning and takes 'Text'.
 {-# WARNING traceM "'traceM' remains in code" #-}
 traceM :: (Monad m) => Text -> m ()
-traceM s = trace (unpack s) pass
+traceM s = trace (toString s) pass
 
 -- | Version of 'Debug.Trace.traceId' that leaves warning and takes 'Text'.
 {-# WARNING traceId "'traceId' remains in code" #-}

src/Relude/DeepSeq.hs

@@ -1,13 +1,14 @@
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
--- | This module contains useful functions to evaluate expressions to weak-head
+This module contains useful functions to evaluate expressions to weak-head
--- normal form or just normal form. Useful to force traces or @error@ inside
+normal form or just normal form. Useful to force traces or @error@ inside
--- monadic computation or to remove space leaks.
+monadic computation or to remove space leaks.
+-}
 
 module Relude.DeepSeq
        ( module Control.DeepSeq

src/Relude/Exception.hs

@@ -3,15 +3,16 @@
 {-# LANGUAGE Safe                  #-}
 {-# LANGUAGE ViewPatterns          #-}
 
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
--- | Re-exports most useful functionality from 'safe-exceptions'. Also
+Re-exports most useful functionality from 'safe-exceptions'. Also
--- provides some functions to work with exceptions over 'MonadError'.
+provides some functions to work with exceptions over 'MonadError'.
+-}
 
 module Relude.Exception
        ( module Control.Exception
@@ -53,6 +54,7 @@ bug e = impureThrow (Bug (E.toException e) callStack)
 writing something like this:
 
 @
+isNonCriticalExc :: SomeException -> Bool
 isNonCriticalExc e
     | Just (_ :: NodeAttackedError) <- fromException e = True
     | Just DialogUnexpected{} <- fromException e = True
@@ -62,6 +64,7 @@ isNonCriticalExc e
 you can use 'Exc' pattern synonym:
 
 @
+isNonCriticalExc :: SomeException -> Bool
 isNonCriticalExc = \case
     Exc (_ :: NodeAttackedError) -> True  -- matching all exceptions of type 'NodeAttackedError'
     Exc DialogUnexpected{} -> True

src/Relude/Extra/Bifunctor.hs

@@ -1,3 +1,20 @@
+{- |
+Copyright:  (c) 2018 Kowainik
+License:    MIT
+Maintainer: Kowainik <xrom.xkov@gmail.com>
+
+Useful combinators for bifunctors inside functors. This set of functions is
+useful when you want to work with types like these ones:
+
+@
+foo :: IO (Either a b)
+bar :: IO (a, b)
+
+baz :: Maybe (Either a b)
+qux :: Maybe (a, b)
+@
+-}
+
 module Relude.Extra.Bifunctor
        ( bimapF
        , firstF
@@ -6,11 +23,26 @@ module Relude.Extra.Bifunctor
 
 import Relude
 
+{- | Fmaps functions for nested bifunctor. Short for @fmap (bimap f g)@.
+
+>>> bimapF not length $ Just (False, ['a', 'b'])
+Just (True,2)
+-}
 bimapF  :: (Functor f, Bifunctor p) => (a -> c) -> (b -> d) -> f (p a b) -> f (p c d)
 bimapF f g = fmap (bimap f g)
 
+{- | Short for @fmap . first@.
+
+>>> firstF not $ Just (False, ['a', 'b'])
+Just (True,"ab")
+-}
 firstF  :: (Functor f, Bifunctor p) => (a -> c) -> f (p a b) -> f (p c b)
 firstF = fmap . first
 
+{- | Short for @fmap . second@.
+
+>>> secondF length  $ Just (False, ['a', 'b'])
+Just (False,2)
+-}
 secondF  :: (Functor f, Bifunctor p) => (b -> d) -> f (p a b) -> f (p a d)
 secondF = fmap . second

src/Relude/Extra/CallStack.hs

@@ -1,18 +1,21 @@
-{- | Contains useful functions to work with GHC callstack.
+{- |
+Copyright:  (c) 2018 Kowainik
+License:    MIT
+Maintainer: Kowainik <xrom.xkov@gmail.com>
+
+Contains useful functions to work with GHC callstack.
 -}
 
 module Relude.Extra.CallStack
        ( ownName
+       , callerName
        ) where
 
 import Relude
 
-import GHC.Stack (getCallStack)
-
--- TODO: better name?
 {- | This function returns the name of its caller function, but it requires
 that the caller function has 'HasCallStack' constraint. Otherwise, it returns
-@"ownName"@.
+@"<unknown>"@.
 
 >>> foo :: HasCallStack => String; foo = ownName
 >>> foo
@@ -24,4 +27,21 @@ that the caller function has 'HasCallStack' constraint. Otherwise, it returns
 ownName :: HasCallStack => String
 ownName = case getCallStack callStack of
     _:caller:_ -> fst caller
-    _          -> "ownName"
+    _          -> "<unknown>"
+
+{- | This function returns the name of its caller of the caller function, but it
+requires that the caller function and caller of the caller function have
+'HasCallStack' constraint. Otherwise, it returns @"<unkown>"@. It's useful for
+logging:
+
+>>> log :: HasCallStack => String -> IO (); log s = putStrLn $ callerName ++ ":" ++ s
+>>> greeting :: HasCallStack => IO (); greeting = log "Starting..." >> putStrLn "Hello!" >> log "Ending..."
+>>> greeting
+greeting:Starting...
+Hello!
+greeting:Ending...
+-}
+callerName :: HasCallStack => String
+callerName = case getCallStack callStack of
+    _:_:caller:_ -> fst caller
+    _            -> "<unknown>"

src/Relude/Extra/Enum.hs

@@ -1,10 +1,19 @@
 {-# LANGUAGE ScopedTypeVariables #-}
 {-# LANGUAGE TypeApplications    #-}
 
+{- |
+Copyright:  (c) 2018 Kowainik
+License:    MIT
+Maintainer: Kowainik <xrom.xkov@gmail.com>
+
+Mini @bounded-enum@ framework inside @relude@.
+-}
+
 module Relude.Extra.Enum
        ( universe
        , inverseMap
        , next
+       , prec
        , safeToEnum
        ) where
 
@@ -26,7 +35,14 @@ import qualified Data.Map.Strict as M
 universe :: (Bounded a, Enum a) => [a]
 universe = [minBound .. maxBound]
 
-{- | Creates a function that is the inverse of a given function @f@.
+{- | @inverseMap f@ creates a function that is the inverse of a given function
+@f@. It does so by constructing 'M.Map' for every value @f a@. The
+implementation makes sure that the 'M.Map' is constructed only once and then
+shared for every call.
+
+The complexity of reversed mapping though is \(\mathcal{O}(\log n)\).
+
+Usually you want to use 'inverseMap' to inverse 'show' function.
 
 >>> data Color = Red | Green | Blue deriving (Show, Enum, Bounded)
 >>> parse = inverseMap show :: String -> Maybe Color
@@ -35,17 +51,15 @@ Just Red
 >>> parse "Black"
 Nothing
 -}
-inverseMap :: forall a k. (Bounded a, Enum a, Ord k)
+inverseMap :: forall a k . (Bounded a, Enum a, Ord k)
-           => (a -> k)
+           => (a -> k) -> (k -> Maybe a)
-           -> k
+inverseMap f = \k -> M.lookup k dict
-           -> Maybe a
+  where
-inverseMap f = \x -> M.lookup x dict
+    dict :: M.Map k a
-    where
+    dict = M.fromList $ zip (map f univ) univ
-        dict :: M.Map k a
-        dict = M.fromList $ zip (map f univ) univ
 
-        univ :: [a]
+    univ :: [a]
-        univ = universe
+    univ = universe
 
 {- | Like 'succ', but doesn't fail on 'maxBound'. Instead it returns 'minBound'.
 
@@ -55,13 +69,26 @@ True
 False
 >>> succ True
 *** Exception: Prelude.Enum.Bool.succ: bad argument
-
 -}
 next  :: (Eq a, Bounded a, Enum a) => a -> a
 next e
     | e == maxBound = minBound
     | otherwise     = succ e
 
+{- | Like 'pred', but doesn't fail on 'minBound'. Instead it returns 'maxBound'.
+
+>>> prec False
+True
+>>> prec True
+False
+>>> pred False
+*** Exception: Prelude.Enum.Bool.pred: bad argument
+-}
+prec  :: (Eq a, Bounded a, Enum a) => a -> a
+prec e
+    | e == minBound = maxBound
+    | otherwise     = pred e
+
 {- | Returns 'Nothing' if given 'Int' outside range.
 
 >>> safeToEnum @Bool 0

src/Relude/Extra/Group.hs

@@ -1,10 +1,12 @@
 {-# LANGUAGE ScopedTypeVariables #-}
 {-# LANGUAGE TypeFamilies        #-}
 
-{-
+{- |
-Copyright: (c) 2017-2018 Serokelll
+Copyright:  (c) 2018 Kowainik
-           (c) 2018 Kowainik
+License:    MIT
-License: MIT
+Maintainer: Kowainik <xrom.xkov@gmail.com>
+
+Polymorphic grouping functions.
 -}
 
 module Relude.Extra.Group

src/Relude/Extra/Map.hs

@@ -1,7 +1,12 @@
 {-# LANGUAGE TypeFamilies #-}
 
-{- | Contains implememtation of polymorhic type classes for things like 'Set'
+{- |
-and 'Map'.
+Copyright:  (c) 2018 Kowainik
+License:    MIT
+Maintainer: Kowainik <xrom.xkov@gmail.com>
+
+Contains implementation of polymorhic type classes for data types 'Set' and
+'Map'.
 -}
 
 module Relude.Extra.Map
@@ -38,7 +43,7 @@ import qualified Data.Set as S
 -- Static Map
 ----------------------------------------------------------------------------
 
-{- | Read-only map or set. Contains polymorhic functions which work for both
+{- | Read-only map or set. Contains polymorphic functions which work for both
 sets and maps.
 -}
 class StaticMap t where

src/Relude/Extra/Newtype.hs

@@ -1,6 +1,11 @@
 {-# LANGUAGE ScopedTypeVariables #-}
 
-{- | Functions to ease work with newtypes.
+{- |
+Copyright:  (c) 2018 Kowainik
+License:    MIT
+Maintainer: Kowainik <xrom.xkov@gmail.com>
+
+Functions to ease work with newtypes.
 -}
 
 module Relude.Extra.Newtype

src/Relude/Foldable.hs

@@ -1,4 +1,10 @@
--- | This module exports all 'Foldable' and 'Traversable' related stuff.
+{- |
+Copyright:  (c) 2018 Kowainik
+License:    MIT
+Maintainer: Kowainik <xrom.xkov@gmail.com>
+
+This module exports all 'Foldable' and 'Traversable' related stuff.
+-}
 
 module Relude.Foldable
        ( module Relude.Foldable.Fold

src/Relude/Foldable/Fold.hs

@@ -7,13 +7,20 @@
 
 {-# OPTIONS_GHC -fno-warn-unticked-promoted-constructors #-}
 
--- | Fixes and additions to 'Foldable'.
+{- |
+Copyright: (c) 2016 Stephen Diehl
+           (c) 20016-2018 Serokell
+           (c) 2018 Kowainik
+License:    MIT
+Maintainer: Kowainik <xrom.xkov@gmail.com>
+
+Fixes and additions to 'Foldable'.
+-}
 
 module Relude.Foldable.Fold
        ( flipfoldl'
        , foldMapA
        , foldMapM
-       , safeHead
        , sum
        , product
 
@@ -24,6 +31,10 @@ module Relude.Foldable.Fold
        , anyM
        , andM
        , orM
+
+         -- * Internals
+       , DisallowElem
+       , ElemErrorMessage
        ) where
 
 import GHC.TypeLits (ErrorMessage (..), TypeError)
@@ -35,41 +46,47 @@ import Relude.Container.Reexport (HashSet, Set)
 import Relude.Foldable.Reexport (Foldable (..))
 import Relude.Function (flip, (.))
 import Relude.Functor ((<$>))
-import Relude.Monad.Reexport (Maybe (..), Monad (..))
+import Relude.Monad.Reexport (Monad (..))
 import Relude.Monoid (Monoid (..))
 
 import qualified Data.Foldable as F
 
 -- $setup
 -- >>> :set -XOverloadedStrings
--- >>> import Relude.Base (String, Rational, even, (/))
+-- >>> import Relude.Base (Int, String, Rational, even, (/))
 -- >>> import Relude.Bool (when)
+-- >>> import Relude.List (replicate)
 -- >>> import Relude.Monad (Maybe (..), (>=>))
 -- >>> import Relude.Print (print, putTextLn)
 -- >>> import Relude.String (Text, readMaybe)
 -- >>> import qualified Data.HashMap.Strict as HashMap
 
-safeHead :: Foldable f => f a -> Maybe a
-safeHead = foldr (\x _ -> Just x) Nothing
-{-# INLINE safeHead #-}
-
 {- | Similar to 'foldl'' but takes a function with its arguments flipped.
 
 >>> flipfoldl' (/) 5 [2,3] :: Rational
 15 % 2
-
 -}
 flipfoldl' :: Foldable f => (a -> b -> b) -> b -> f a -> b
 flipfoldl' f = foldl' (flip f)
 {-# INLINE flipfoldl' #-}
 
-foldMapA :: (Monoid b, Applicative m, Foldable f) => (a -> m b) -> f a -> m b
+{- | Polymorphic version of @concatMapA@ function.
+
+>>> foldMapA @[Int] (Just . replicate 3) [1..3]
+Just [1,1,1,2,2,2,3,3,3]
+-}
+foldMapA :: forall b m f a . (Monoid b, Applicative m, Foldable f) => (a -> m b) -> f a -> m b
 foldMapA f = foldr step (pure mempty)
   where
     step a mb = mappend <$> f a <*> mb
 {-# INLINE foldMapA #-}
 
-foldMapM :: (Monoid b, Monad m, Foldable f) => (a -> m b) -> f a -> m b
+{- | Polymorphic version of @concatMapM@ function.
+
+>>> foldMapM @[Int] (Just . replicate 3) [1..3]
+Just [1,1,1,2,2,2,3,3,3]
+-}
+foldMapM :: forall b m f a . (Monoid b, Monad m, Foldable f) => (a -> m b) -> f a -> m b
 foldMapM f xs = foldr step return xs mempty
   where
     step x r z = f x >>= \y -> r $! z `mappend` y

src/Relude/Foldable/Reexport.hs

@@ -1,3 +1,11 @@
+{- |
+Copyright:  (c) 2018 Kowainik
+License:    MIT
+Maintainer: Kowainik <xrom.xkov@gmail.com>
+
+Reexports "Data.Foldable" and "Data.Traversable".
+-}
+
 module Relude.Foldable.Reexport
        ( module Data.Foldable
        , module Data.Traversable

src/Relude/Function.hs

@@ -1,11 +1,12 @@
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
--- | This module reexports very basic and primitive functions and function combinators.
+This module reexports very basic and primitive functions and function combinators.
+-}
 
 module Relude.Function
        ( module Data.Function

src/Relude/Functor.hs

@@ -1,6 +1,14 @@
 {-# LANGUAGE Safe #-}
 
--- | Convenient functions to work with 'Functor'.
+{- |
+Copyright: (c) 2016 Stephen Diehl
+           (c) 20016-2018 Serokell
+           (c) 2018 Kowainik
+License:    MIT
+Maintainer: Kowainik <xrom.xkov@gmail.com>
+
+Convenient functions to work with 'Functor'.
+-}
 
 module Relude.Functor
        ( module Relude.Functor.Fmap

src/Relude/Functor/Fmap.hs

@@ -1,14 +1,15 @@
 {-# LANGUAGE CPP  #-}
 {-# LANGUAGE Safe #-}
 
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
--- | This module contains useful functions to work with 'Functor' type class.
+This module contains useful functions to work with 'Functor' type class.
+-}
 
 module Relude.Functor.Fmap
        ( (<<$>>)

src/Relude/Functor/Reexport.hs

@@ -1,13 +1,14 @@
 {-# LANGUAGE Safe #-}
 
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
--- | This module reexports functionality regarding 'Functor' type class.
+Reexports functionality regarding 'Functor' and 'Bifunctor' typeclasses.
+-}
 
 module Relude.Functor.Reexport
        ( module Control.Arrow

src/Relude/Lifted.hs

@@ -1,13 +1,14 @@
 {-# LANGUAGE Safe #-}
 
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
--- | Lifted versions of base functions.
+Lifted versions of base functions.
+-}
 
 module Relude.Lifted
        ( module Relude.Lifted.Concurrent

src/Relude/Lifted/Concurrent.hs

@@ -1,13 +1,14 @@
 {-# LANGUAGE Safe #-}
 
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
--- | Concurrency useful and common functions.
+Lifted 'MVar' and 'STM' functions.
+-}
 
 module Relude.Lifted.Concurrent
        ( -- * MVar

src/Relude/Lifted/Exit.hs

@@ -1,13 +1,14 @@
 {-# LANGUAGE Safe #-}
 
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
--- | Lifted versions of functions that work with exit processes.
+Lifted versions of functions that work with exit processes.
+-}
 
 module Relude.Lifted.Exit
        ( exitWith

src/Relude/Lifted/File.hs

@@ -1,14 +1,15 @@
 {-# LANGUAGE Safe #-}
 
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
--- | Lifted versions of functions working with files and common IO.
+Lifted versions of functions working with files and common IO.
--- All functions are specialized to 'Data.Text.Text'.
+All functions are specialized to 'Data.Text.Text'.
+-}
 
 module Relude.Lifted.File
        ( appendFile

src/Relude/Lifted/IORef.hs

@@ -1,13 +1,14 @@
 {-# LANGUAGE Safe #-}
 
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
--- | Lifted reexports from 'Data.IORef' module.
+Lifted reexports from 'Data.IORef' module.
+-}
 
 module Relude.Lifted.IORef
        ( IORef

src/Relude/List.hs

@@ -1,18 +1,19 @@
-{-
+{-# LANGUAGE Safe #-}
+
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
+Maintainer: Kowainik <xrom.xkov@gmail.com>
+
+Utility functions to work with lists.
 -}
 
-{-# LANGUAGE Safe #-}
-
--- | Utility functions to work with lists.
-
 module Relude.List
-       ( module Relude.List.Reexport
+       ( module Relude.List.NonEmpty
-       , module Relude.List.Safe
+       , module Relude.List.Reexport
        ) where
 
+import Relude.List.NonEmpty
 import Relude.List.Reexport
-import Relude.List.Safe

src/Relude/List/NonEmpty.hs

@@ -1,15 +1,16 @@
 {-# LANGUAGE Safe #-}
 
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
+Maintainer: Kowainik <xrom.xkov@gmail.com>
+
+This module contains safe functions to work with list type in terms of 'NonEmpty'.
 -}
 
--- | This module contains safe functions to work with list type (mostly with 'NonEmpty').
+module Relude.List.NonEmpty
-
-module Relude.List.Safe
        ( viaNonEmpty
        , uncons
        , whenNotNull
@@ -37,7 +38,6 @@ import Relude.Monad (Maybe (..), Monad (..))
 Just 1
 >>> viaNonEmpty head []
 Nothing
-
 -}
 viaNonEmpty :: (NonEmpty a -> b) -> [a] -> Maybe b
 viaNonEmpty f = fmap f . nonEmpty

src/Relude/List/Reexport.hs

@@ -1,13 +1,14 @@
 {-# LANGUAGE Trustworthy #-}
 
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
--- | This module reexports functinons to work with list, 'NonEmpty' and String types.
+Reexports most of the "Data.List" and "Data.List.NonEmpty".
+-}
 
 module Relude.List.Reexport
        ( module Data.List
@@ -21,5 +22,4 @@ import Data.List (break, cycle, drop, dropWhile, filter, genericDrop, genericLen
                   scanl, scanr, sort, sortBy, sortOn, splitAt, subsequences, tails, take, takeWhile,
                   transpose, unfoldr, unzip, unzip3, zip, zip3, zipWith, (++))
 import Data.List.NonEmpty (NonEmpty (..), head, init, last, nonEmpty, tail)
-
 import GHC.Exts (sortWith)

src/Relude/Monad.hs

@@ -1,13 +1,14 @@
 {-# LANGUAGE Safe #-}
 
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
--- | Reexporting useful monadic stuff.
+Reexporting useful monadic stuff.
+-}
 
 module Relude.Monad
        ( module Relude.Monad.Either

src/Relude/Monad/Either.hs

@@ -3,14 +3,15 @@
 
 {-# OPTIONS_GHC -fno-warn-orphans #-}
 
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
--- | Utilites to work with @Either@ data type.
+Utilites to work with @Either@ data type.
+-}
 
 module Relude.Monad.Either
        ( fromLeft

src/Relude/Monad/Maybe.hs

@@ -1,13 +1,14 @@
 {-# LANGUAGE Safe #-}
 
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
--- | Utility functions to work with 'Data.Maybe' data type as monad.
+Utility functions to work with 'Data.Maybe' data type as monad.
+-}
 
 module Relude.Monad.Maybe
        ( (?:)

src/Relude/Monad/Reexport.hs

@@ -1,13 +1,14 @@
 {-# LANGUAGE Safe #-}
 
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
--- | This module reexports functions to work with monads.
+Reexports functions to work with monads.
+-}
 
 module Relude.Monad.Reexport
        ( -- * Reexport transformers
@@ -31,7 +32,8 @@ module Relude.Monad.Reexport
 
 -- Monad transformers
 import Control.Monad.Except (ExceptT (..), runExceptT)
-import Control.Monad.Reader (MonadReader, Reader, ReaderT (..), ask, asks, local, reader, runReader)
+import Control.Monad.Reader (MonadReader, Reader, ReaderT (..), ask, asks, local, reader, runReader,
+                             withReader, withReaderT)
 import Control.Monad.State.Strict (MonadState, State, StateT (..), evalState, evalStateT, execState,
                                    execStateT, get, gets, modify, modify', put, runState, state,
                                    withState)

src/Relude/Monad/Trans.hs

@@ -1,13 +1,14 @@
 {-# LANGUAGE Safe #-}
 
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
--- | Monad transformers utilities.
+Monad transformers utilities.
+-}
 
 module Relude.Monad.Trans
        ( -- * Convenient functions to work with 'Reader' monad

src/Relude/Monoid.hs

@@ -1,11 +1,12 @@
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
--- | This module reexports functions to work with monoids plus adds extra useful functions.
+Reexports functions to work with monoids plus adds extra useful functions.
+-}
 
 module Relude.Monoid
        ( module Data.Monoid

src/Relude/Nub.hs

@@ -1,11 +1,11 @@
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
-{-| Functions to remove duplicates from a list.
+Functions to remove duplicates from a list.
 
  = Performance
  To check the performance there was done a bunch of benchmarks.

src/Relude/Print.hs

@@ -3,14 +3,15 @@
 {-# LANGUAGE FlexibleInstances #-}
 {-# LANGUAGE Trustworthy       #-}
 
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
--- | Generalization of 'Prelude.putStr' and 'Prelude.putStrLn' functions.
+Generalization of 'Prelude.putStr' and 'Prelude.putStrLn' functions.
+-}
 
 module Relude.Print
        ( Print (..)

src/Relude/String.hs

@@ -1,11 +1,12 @@
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
--- | Type classes for convertion between different string representations.
+Type classes for convertion between different string representations.
+-}
 
 module Relude.String
        ( module Relude.String.Conversion

src/Relude/String/Conversion.hs

@@ -5,18 +5,19 @@
 {-# LANGUAGE MultiParamTypeClasses  #-}
 {-# LANGUAGE TypeSynonymInstances   #-}
 
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
--- | This module implements type class which allow to have conversion to and
+This module implements type class which allow to have conversion to and from
--- from 'Text', 'String' and 'ByteString' types (including both strict and lazy
+'Text', 'String' and 'ByteString' types (including both strict and lazy
--- versions). Usually you need to export 'Text' modules qualified and use
+versions). Usually you need to export 'Text' modules qualified and use 'T.pack'
--- 'T.pack' \/ 'T.unpack' functions to convert to\/from 'Text'. Now you can
+\/ 'T.unpack' functions to convert to\/from 'Text'. Now you can just use
--- just use 'toText' \/ 'toString' functions.
+'toText' \/ 'toString' functions.
+-}
 
 module Relude.String.Conversion
        ( -- * Convenient type aliases

src/Relude/String/Reexport.hs

@@ -1,11 +1,12 @@
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
--- | This module reexports functions to work with 'Text' and 'ByteString' types.
+Reexports functions to work with 'Text' and 'ByteString' types.
+-}
 
 module Relude.String.Reexport
        ( -- * String

src/Relude/Unsafe.hs

@@ -1,16 +1,15 @@
 {-# LANGUAGE Unsafe #-}
 
-{-
+{- |
 Copyright: (c) 2016 Stephen Diehl
            (c) 20016-2018 Serokell
            (c) 2018 Kowainik
-License: MIT
+License:    MIT
--}
+Maintainer: Kowainik <xrom.xkov@gmail.com>
 
-{- | Unsafe functions to work with lists and 'Maybe'.
+Unsafe functions to work with lists and 'Maybe'. Sometimes unavoidable but it's
-Sometimes unavoidable but better don't use them. This module
+better not to use them. This module is intended to be imported qualified and
-is intended to be imported qualified and it's not even included
+it's not even included in default prelude exports.
-in default prelude exports.
 
 @
 import qualified Relude.Unsafe as Unsafe
@@ -18,17 +17,12 @@ import qualified Relude.Unsafe as Unsafe
 foo :: [a] -> a
 foo = Unsafe.head
 @
-
 -}
 
 module Relude.Unsafe
-       ( head
+       ( module Data.List
-       , tail
+       , module Data.Maybe
-       , init
-       , last
        , at
-       , (!!)
-       , fromJust
        ) where
 
 import Data.List (head, init, last, tail, (!!))