[#135] Add documentation about internal module structure (#162)

* [#135] Add documentation about internal module structure

* Improve English and formatting

CHANGES.md

@@ -1,6 +1,8 @@
 1.1.1
 =====
 
+* [#135](https://github.com/serokell/universum/issues/135):
+  Add documentation regarding internal module structure.
 * [#113](https://github.com/serokell/universum/issues/113):
   Annotate `at` function from `Unsafe` module and `ordNub`
   function from `Nub` module with `liquidhaskell`.

README.md

@@ -12,10 +12,13 @@ Universum
 
 1. **Excellent documentation**: tutorial, migration guide from `Prelude`,
    Haddock with examples for (almost) every function,
-   all examples are tested with [`doctest`](http://hackage.haskell.org/package/doctest).
+   all examples are tested with [`doctest`](http://hackage.haskell.org/package/doctest),
+   documenation regarding internal module structure.
 2. `universum`-specific [HLint](http://hackage.haskell.org/package/hlint) rules:
    [`.hlint.yaml`](https://github.com/serokell/universum/blob/master/.hlint.yaml)
-3. Focus on safety, convenience and efficiency.
+3. Only a few LiquidHaskell properties right now, but LiquidHaskell is on Travis
+   CI and other properties are just waiting to be added!
+4. Focus on safety, convenience and efficiency.
 
 What is this file about?
 ------------------------
@@ -116,10 +119,15 @@ Then add the following import to your modules:
 import Universum
 ```
 
-If you're using [Emacs](https://www.gnu.org/software/emacs/), you can
+If you're using [Emacs](https://www.gnu.org/software/emacs/) and don't want to
+type `import Universum` manually every time, you can
 [modify your configs](https://github.com/serokell/universum/issues/8#issuecomment-276444879)
-a little bit if you don't want to type `import Universum` manually every time.
+a little bit.
 
+If you want to get familiar with `universum` internal structure, you can just
+read top-level documentation for
+[`Universum`](http://hackage.haskell.org/package/universum/docs/Universum.html)
+module.
 
 Gotchas [↑](#structure-of-this-tutorial)
 -------
@@ -291,7 +299,7 @@ Migration guide from Prelude [↑](#structure-of-this-tutorial)
 ----------------------------
 
 In order to replace default `Prelude` with `universum` you should start with instructions given in
-[how to use universum](https://github.com/serokell/universum#how-to-use-universum) section.
+[how to use universum](https://github.com/serokell/universum#how-to-use-universum-) section.
 
 This section describes what you need to change to make your code compile with `universum`.
 

src/Universum.hs

@@ -1,14 +1,62 @@
 {-# LANGUAGE Trustworthy #-}
 
--- | Main module that reexports all functionality allowed to use
--- without importing any other modules. Just add next lines to your
--- module to replace default ugly 'Prelude' with better one.
---
--- @
---     {-\# LANGUAGE NoImplicitPrelude \#-}
---
---     import Universum
--- @
+{- | 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.
+
+@
+\{\-\# LANGUAGE NoImplicitPrelude \#\-\}
+
+__import__ "Universum"
+@
+
+This documentation section contains description of internal module structure to
+help navigate between modules, search for interesting functionalities and
+understand where you need to put your new changes.
+
+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 @Universum.SomeTheme.Reexport@ and our own functions and types are in
+@Universum.SomeTheme.SomeName@. For example, see modules
+"Universum.Container.Class" and "Universum.Container.Reexport".
+
+Below is a short description of what you can find under different modules:
+
+* __"Universum.Applicative"__: reexports from "Control.Applicative" and some
+  general-purpose applicative combinators.
+* __"Universum.Base"__: different general types and type classes from @base@
+  package ('Int', 'Num', 'Generic', etc.) not exported by other modules.
+* __"Universum.Bool"__: 'Bool' data type with different predicates and combinators.
+* __"Universum.Container"__: 'Foldable' replacement, types from @containers@
+   and @unordered-containers@ and @vector@ packages.
+* __"Universum.Debug"__: @trace@-like debugging functions with compile-time
+  warnings (so you don't forget to remove them)
+* __"Universum.DeepSeq"__: reexports from "Control.DeepSeq" module and
+  functions to evaluate expressions to weak-head normal form or normal form.
+* __"Universum.Exception"__: reexports "Control.Exception.Safe" from
+  @safe-exceptions@ package, 'bug' as better 'error', 'Exc' pattern synonym for
+  convenient pattern-matching on exceptions.
+* __"Universum.Function"__: almost everything from "Data.Function" module.
+* __"Universum.Functor"__: reexports from "Data.Functor", "Data.Bifunctor",
+  other useful 'Functor' combinators.
+* __"Universum.Lifted"__: lifted to 'MonadIO' functions to work with console,
+  files, 'IORef's, 'MVar's, etc.
+* __"Universum.List"__: big chunk of "Data.List", 'NonEmpty' type and
+  functions for this type ('head', 'tail', 'last', 'init').
+* __"Universum.Monad"__: monad transormers, combinators for 'Maybe' and 'Either'.
+* __"Universum.Monoid"__: reexports from "Data.Monoid" and "Data.Semigroup".
+* __"Universum.Nub"__: better versions of @nub@ function for list.
+* __"Universum.Print"__: polymorphic 'putStrLn' function and functions to print 'Text'.
+* __"Universum.String"__: reexports from @text@ and @bytestring@ packages with
+    conversion functions between different textual types.
+* __"Universum.TypeOps"__: convenient and fancy type-level operators.
+* __"Universum.Unsafe"__: unsafe functions (produce 'error').
+  Not exported by "Universum" module by default.
+* __"Universum.VarArg"__: variadic composition operator '...'.
+-}
 
 module Universum
        ( -- * Reexports from base and from modules in this repo

src/Universum/Unsafe.hs

@@ -28,7 +28,6 @@ import Data.List (head, init, last, tail, (!!))
 import Data.Maybe (fromJust)
 
 import Universum.Base (Int)
-import Universum.Function (flip)
 
 -- Non empty list definition for @liquidhaskell@.
 {-@ type NonEmptyList a = {xs : [a] | len xs > 0} @-}