[#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,49 +1,63 @@
 {-# 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
-without importing any other modules. Just add next lines to your
-module to replace default 'Prelude' with better one.
+The main module that reexports all functionality. It's allowed to use it without
+importing any other modules. If you want to use @relude@ per-module basis then
+just add next lines to your module to replace default 'Prelude':
 
 @
 \{\-\# LANGUAGE NoImplicitPrelude \#\-\}
 
 __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
-this module contains. Some /themes/ contain a great amount of both reexported
-functions and functions of our own. To make it easier to understand these huge
-chunks of functions, all reexported stuff is moved into separate module with
-name @Relude.SomeTheme.Reexport@ and our own functions and types are in
-@Relude.SomeTheme.SomeName@. For example, see modules
-"Relude.Container.Class" and "Relude.Container.Reexport".
+meaning or __category__. Name of the module should give you hints regarding what
+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 enormous
+chunks of functions, all reexported stuff is moved into the separate module with
+name @Relude.SomeCategory.Reexport@ and our own functions and types are in
+@Relude.SomeCategory.SomeName@. For example, see modules
+"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
-  @safe-exceptions@ package, 'bug' as better 'error', 'Exc' pattern synonym for
-  convenient pattern-matching on exceptions.
+* __"Relude.Exception"__: reexports "Control.Exception", introduces 'bug'
+  function as better 'error' and 'Exc' pattern synonym for convenient
+  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
--- (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.
+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>)
+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 Unsafe       #-}
+{-# LANGUAGE CPP    #-}
+{-# 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>
--- package.
+Reexports from @Data.*@ and @GHC.*@ modules of
+<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