[#78] Better docs, prepare for the release (#118)

* [#78] Better docs, prepare for the release

Resolves #78

* Update co-log-core/src/Colog/Core/Action.hs 

Co-Authored-By: chshersh <[email protected]>

* Minor fixes to docs

* Minor

Author: chshersh

README.md

@@ -4,7 +4,7 @@
 [![Build status](https://img.shields.io/travis/kowainik/co-log.svg?logo=travis)](https://travis-ci.org/kowainik/co-log)
 
 |                   |                                    |                                           |                                                       |
-| :------------     | :--------------------------------- | :---------------------------------------: | :---------------------------------------------------- |
+| :------------     | :--------------------------------- | :---------------------------------------- | :---------------------------------------------------- |
 | `co-log-core`     | [![Hackage][hk-img-core]][hk-core] | [![Stackage LTS][lts-img-core]][lts-core] | [![Stackage Nightly][nightly-img-core]][nightly-core] |
 | `co-log`          | [![Hackage][hk-img]][hk]           | [![Stackage LTS][lts-img]][lts]           | [![Stackage Nightly][nightly-img]][nightly]           |
 | `co-log-polysemy` | [![Hackage][hk-img-ps]][hk-ps]     | [![Stackage LTS][lts-img-ps]][lts-ps]     | [![Stackage Nightly][nightly-img-ps]][nightly-ps]     |
@@ -24,8 +24,10 @@ The repository contains the following packages:
   on `co-log-core` and the [`polysemy`](http://hackage.haskell.org/package/polysemy) extensible effects library.
 * [`co-log-benchmark`](co-log-benchmark): Benchmarks of the `co-log` library.
 
-See [How to start using `co-log`?](co-log/README.md) for simple example of the
-`co-log` library usage.
+See the following tutorial series about the library:
+
+* [Intro: Using `LogAction`](https://github.com/kowainik/co-log/blob/master/co-log/tutorials/1-intro/Intro.md)
+* [Using custom monad that stores `LogAction` inside its environment](https://github.com/kowainik/co-log/blob/master/co-log/tutorials/2-custom/Custom.md)
 
 ## Benchmarks
 

co-log-core/CHANGELOG.md

@@ -3,14 +3,16 @@
 `co-log-core` uses [PVP Versioning][1].
 The change log is available [on GitHub][2].
 
-## Unreleased
+## 0.1.2.0 — May 5, 2019
 
 * [#85](https://github.com/kowainik/co-log/issues/85):
   Move `overLogAction` to `HasLog` typeclass
 * [#101](https://github.com/kowainik/co-log/issues/101):
   Add `logActionL` lens with default implementation to `HasLog` type class.
 * [#99](https://github.com/kowainik/co-log/issues/99):
   Add comonadic combinators: `duplicate` and `multiplicate`.
+* [#78](https://github.com/kowainik/co-log/issues/78):
+  Improve documentation significantly.
 
 ## 0.1.1 — Nov 15, 2018
 

co-log-core/co-log-core.cabal

@@ -1,6 +1,6 @@
 cabal-version:       2.4
 name:                co-log-core
-version:             0.1.1
+version:             0.2.0.0
 synopsis:            Composable Contravariant Comonadic Logging Library
 description:
     This package provides core types and functions to work with the @LogAction@ data type which is both simple and powerful.
@@ -14,6 +14,12 @@ description:
     The ideas behind this package are described in the following blog post:
     .
     * [co-log: Composable Contravariant Combinatorial Comonadic Configurable Convenient Logging](https://kowainik.github.io/posts/2018-09-25-co-log)
+    .
+    See the following packages for different implementations based on @co-log-core@:
+    .
+    * [co-log](http://hackage.haskell.org/package/co-log): taggless final implementations.
+    * [co-log-polysemy](http://hackage.haskell.org/package/co-log-polysemy): extensible
+      effects implementation based on @polysemy@.
 
 homepage:            https://github.com/kowainik/co-log
 bug-reports:         https://github.com/kowainik/co-log/issues

co-log-core/src/Colog/Core.hs

@@ -3,7 +3,27 @@ Copyright:  (c) 2018-2019 Kowainik
 License:    MIT
 Maintainer: Kowainik <[email protected]>
 
-Exports all core functionality.
+Exports all core functionality. @co-log-core@ is a lightweight package that
+defines only core data type and various combinators to work with it.
+
+Fundamentals of @co-log-core@ are based on the following data type:
+
+@
+__newtype__ LogAction m msg = LogAction
+    { unLogAction :: msg -> m ()
+    }
+@
+
+This data type provides extremely composable and flexible interface by having
+many instances of the standard algebraic data types.
+
+The package has the following structure:
+
+* __"Colog.Core.Action":__ definition of the main data type and its combinators.
+* __"Colog.Core.Class":__ 'HasLog' typeclass that describes how different values
+  (e.g. application environment) can store and modify 'LogAction'.
+* __"Colog.Core.IO":__ basic loggers that work with 'Control.Monad.IO.Class.MonadIO' and 'String'.
+* __"Colog.Core.Severity":__ logger severity.
 -}
 module Colog.Core
        ( module Colog.Core.Action

co-log-core/src/Colog/Core/Action.hs

@@ -18,6 +18,7 @@ module Colog.Core.Action
        , foldActions
 
          -- * Contravariant combinators
+         -- $contravariant
        , cfilter
        , cmap
        , (>$<)
@@ -26,18 +27,21 @@ module Colog.Core.Action
        , cmapM
 
          -- * Divisible combinators
+         -- $divisible
        , divide
        , conquer
        , (>*<)
        , (>*)
        , (*<)
 
          -- * Decidable combinators
+         -- $decidable
        , lose
        , choose
        , (>|<)
 
          -- * Comonadic combinators
+         -- $comonad
        , extract
        , extend
        , (=>>)
@@ -77,8 +81,11 @@ can be either 'IO' or some custom pure monad.
 Key design point here is that 'LogAction' is:
 
 * 'Semigroup'
-* Contravariant
-* Comonad
+* 'Monoid'
+* 'Data.Functor.Contravariant.Contravariant'
+* 'Data.Functor.Contravariant.Divisible.Divisible'
+* 'Data.Functor.Contravariant.Divisible.Decidable'
+* 'Control.Comonad.Comonad'
 -}
 newtype LogAction m msg = LogAction
     { unLogAction :: msg -> m ()
@@ -193,6 +200,16 @@ foldActions actions = LogAction $ \a -> for_ actions $ \(LogAction action) -> ac
 -- Contravariant combinators
 ----------------------------------------------------------------------------
 
+{- $contravariant
+
+Combinators that implement interface in the spirit of the following typeclass:
+
+@
+__class__ Contravariant f __where__
+    contramap :: (a -> b) -> f b -> f a
+@
+-}
+
 {- | Takes predicate and performs given logging action only if predicate returns
 'True' on input logging message.
 -}
@@ -320,6 +337,17 @@ cmapM f (LogAction action) = LogAction (f >=> action)
 -- Divisible combinators
 ----------------------------------------------------------------------------
 
+{- $divisible
+
+Combinators that implement interface in the spirit of the following typeclass:
+
+@
+__class__ Contravariant f => Divisible f __where__
+    conquer :: f a
+    divide  :: (a -> (b, c)) -> f b -> f c -> f a
+@
+-}
+
 {- | @divide@ combinator from @Divisible@ type class.
 
 >>> logInt = LogAction print
@@ -383,6 +411,17 @@ infixr 4 *<
 -- Decidable combinators
 ----------------------------------------------------------------------------
 
+{- $decidable
+
+Combinators that implement interface in the spirit of the following typeclass:
+
+@
+__class__ Divisible f => Decidable f __where__
+    lose   :: (a -> Void) -> f a
+    choose :: (a -> Either b c) -> f b -> f c -> f a
+@
+-}
+
 -- | @lose@ combinator from @Decidable@ type class.
 lose :: (a -> Void) -> LogAction m a
 lose f = LogAction (absurd . f)
@@ -418,6 +457,18 @@ infixr 3 >|<
 -- Comonadic combinators
 ----------------------------------------------------------------------------
 
+{- $comonad
+
+Combinators that implement interface in the spirit of the following typeclass:
+
+@
+__class__ Functor w => Comonad w __where__
+    extract   :: w a -> a
+    duplicate :: w a -> w (w a)
+    extend    :: (w a -> b) -> w a -> w b
+@
+-}
+
 {- | If @msg@ is 'Monoid' then 'extract' performs given log action by passing
 'mempty' to it.
 
@@ -434,15 +485,15 @@ extract action = unLogAction action mempty
 
 >>> f (LogAction l) = l ".f1" *> l ".f2"
 >>> g (LogAction l) = l ".g"
->>> unLogAction logStringStdout "foo"
+>>> logStringStdout <& "foo"
 foo
->>> unLogAction (extend f logStringStdout) "foo"
+>>> extend f logStringStdout <& "foo"
 foo.f1
 foo.f2
->>> unLogAction (extend g $ extend f logStringStdout) "foo"
+>>> (extend g $ extend f logStringStdout) <& "foo"
 foo.g.f1
 foo.g.f2
->>> unLogAction (logStringStdout =>> f =>> g) "foo"
+>>> (logStringStdout =>> f =>> g) <& "foo"
 foo.g.f1
 foo.g.f2
 -}
@@ -477,7 +528,7 @@ in duplicate logger <& ([3, 4], [42, 10])
 
 __Implementation note:__
 
-True and fair translation of the @duplicate@ function from the 'Comonad'
+True and fair translation of the @duplicate@ function from the 'Control.Comonad.Comonad'
 interface should result in the 'LogAction' of the following form:
 
 @

co-log-core/src/Colog/Core/Class.hs

@@ -29,20 +29,30 @@ functions.
 It also provides the useful lens 'logActionL' with the default implementation using type
 class methods. The default one could be easily overritten under your instances.
 
-TODO: laws
+Every instance of the this typeclass should satisfy the following laws:
+
+1. __Set-Get:__ @'getLogAction' ('setLogAction' l env) ≡ l@
+2. __Get-Set:__ @'setLogAction' ('getLogAction' env) env ≡ env@
+3. __Set-Set:__ @'setLogAction' l2 ('setLogAction' l1 env) ≡ 'setLogAction' l2 env@
+4. __Set-Over:__ @'overLogAction' f env ≡ 'setLogAction' (f $ 'getLogAction' env) env@
 -}
 class HasLog env msg m where
     {-# MINIMAL getLogAction, (setLogAction | overLogAction) #-}
+
+    -- | Extracts 'LogAction' from the environment.
     getLogAction :: env -> LogAction m msg
 
+    -- | Sets 'LogAction' to the given one inside the environment.
     setLogAction :: LogAction m msg -> env -> env
     setLogAction = overLogAction . const
     {-# INLINE setLogAction #-}
 
+    -- | Applies function to the 'LogAction' inside the environment.
     overLogAction :: (LogAction m msg -> LogAction m msg) -> env -> env
     overLogAction f env = setLogAction (f $ getLogAction env) env
     {-# INLINE overLogAction #-}
 
+    -- | Lens for 'LogAction' inside the environment.
     logActionL :: Lens' env (LogAction m msg)
     logActionL = lens getLogAction (flip setLogAction)
     {-# INLINE logActionL #-}

co-log-core/src/Colog/Core/IO.hs

@@ -3,7 +3,11 @@ Copyright:  (c) 2018-2019 Kowainik
 License:    MIT
 Maintainer: Kowainik <[email protected]>
 
-Introduces logging actions working in 'MonadIO'.
+Introduces logging actions working in 'MonadIO'. These actions are very basic
+and inefficient because they use the 'String' data type. If you don't want to
+have extra dependencies and performance of logging is not the bottleneck of your
+application, then these functions should be enough. Otherwise use functions from
+the "Colog.Actions" module from the @co-log@ package.
 -}
 
 module Colog.Core.IO
@@ -27,13 +31,17 @@ import Colog.Core.Action (LogAction (..))
 import Control.Monad.IO.Class (MonadIO, liftIO)
 import System.IO (Handle, IOMode (AppendMode), hPrint, hPutStrLn, stderr, withFile)
 
+{- $setup
+>>> import Colog.Core.Action
+-}
+
 ----------------------------------------------------------------------------
 -- String
 ----------------------------------------------------------------------------
 
 {- | Action that prints 'String' to stdout.
 
->>> unLogAction logStringStdout "foo"
+>>> logStringStdout <& "foo"
 foo
 -}
 logStringStdout :: MonadIO m => LogAction m String
@@ -43,7 +51,7 @@ logStringStdout = LogAction (liftIO . putStrLn)
 
 {- | Action that prints 'String' to stderr.
 
->>> unLogAction logStringStderr "foo"
+>>> logStringStderr <& "foo"
 foo
 -}
 logStringStderr :: MonadIO m => LogAction m String
@@ -53,7 +61,7 @@ logStringStderr = logStringHandle stderr
 
 {- | Action that prints 'String' to 'Handle'.
 
->>> unLogAction (logStringHandle stderr) "foo"
+>>> logStringHandle stderr <& "foo"
 foo
 -}
 logStringHandle :: MonadIO m => Handle -> LogAction m String
@@ -68,7 +76,7 @@ opening file each time we need to write to it.
 
 Opens file in 'AppendMode'.
 
->>> logger action = unLogAction action "foo"
+>>> logger action = action <& "foo"
 >>> withLogStringFile "/dev/stdout" logger
 foo
 -}
@@ -83,7 +91,7 @@ withLogStringFile path action = withFile path AppendMode $ action . logStringHan
 
 {- | Action that prints to stdout using 'Show'.
 
->>> unLogAction logPrint 5
+>>> logPrint <& 5
 5
 -}
 logPrint :: forall a m . (Show a, MonadIO m) => LogAction m a
@@ -93,7 +101,7 @@ logPrint = LogAction $ liftIO . print
 
 {- | Action that prints to stderr using 'Show'.
 
->>> unLogAction logPrintStderr 5
+>>> logPrintStderr <& 5
 5
 -}
 logPrintStderr :: forall a m . (Show a, MonadIO m) => LogAction m a
@@ -103,7 +111,7 @@ logPrintStderr = logPrintHandle stderr
 
 {- | Action that prints to a 'Handle' using 'Show'.
 
->>> unLogAction (logPrintHandle stderr) 5
+>>> logPrintHandle stderr <& 5
 5
 -}
 logPrintHandle :: forall a m . (Show a, MonadIO m) => Handle -> LogAction m a
@@ -129,7 +137,7 @@ withLogPrintFile path action = withFile path AppendMode $ action . logPrintHandl
 {- | Lifts a LogAction over IO into a more general Monad.
 
 >>> logToStdout = LogAction putStrLn
->>> unLogAction (liftLogIO logToStdout) "foo"
+>>> liftLogIO logToStdout <& "foo"
 foo
 -}
 liftLogIO :: MonadIO m => LogAction IO msg -> LogAction m msg

co-log-core/src/Colog/Core/Severity.hs

@@ -67,7 +67,7 @@ Instead of using full names of the constructors you can instead use one-letter
 patterns. To do so you can import and use the pattern:
 
 @
-import Colog (pattern D)
+__import__ Colog (__pattern__ D)
 
 example :: WithLog env Message m => m ()
 example = log D "I'm using severity pattern"
@@ -89,7 +89,6 @@ pattern W <- Warning where W = Warning
 pattern E <- Error   where E = Error
 {-# COMPLETE D, I, W, E #-}
 
-
 -- | Filters messages by the given 'Severity'.
 filterBySeverity
     :: Applicative m