Improve docs to better explain monads

README.md

@@ -7,7 +7,11 @@
 [![codecov](https://codecov.io/gh/arrow-kt/arrow/branch/master/graph/badge.svg)](https://codecov.io/gh/arrow-kt/arrow)
 
 Λrrow is a library for Typed Functional Programming in Kotlin.
-It includes the most popular data types, type classes and abstractions such as `Option`, `Try`, `Either`, `IO`, `Functor`, `Applicative`, `Monad` and many more empowering users to define pure FP apps and libraries built atop higher order abstractions. Use the below list to learn more about Λrrow's main features.
+
+Arrow aims to provide a *lingua franca* of interfaces and abstractions across Kotlin libraries.
+For this, it includes the most popular data types, type classes and abstractions such as `Option`, `Try`, `Either`, `IO`, `Functor`, `Applicative`, `Monad` to empower users to define pure FP apps and libraries built atop higher order abstractions.
+
+Use the list below to learn more about Λrrow's main features.
 
 - [Documentation](http://arrow-kt.io)
 - [Patterns](http://arrow-kt.io/docs/patterns/glossary/): tutorials and approaches to day-to-day challenges using FP 

infographic/arrow-infographic.txt

@@ -17,20 +17,29 @@
 [<typeclasses>Monad]<-[<typeclasses>MonadError]
 [<typeclasses>Applicative]<-[<typeclasses>Monad]
 [<typeclasses>Semigroup]<-[<typeclasses>Monoid]
+[<typeclasses>Functor]<-[<typeclasses>Traverse]
+[<typeclasses>Foldable]<-[<typeclasses>Traverse]
+[<typeclasses>Async]<-[<instances>Async Instances|IOAsyncInstance|DeferredKAsyncInstance|FluxKAsyncInstance|MonoKAsyncInstance|FlowableKAsyncInstance|MaybeKAsyncInstance|ObservableKAsyncInstance|SingleKAsyncInstance]
+[<typeclasses>Effect]<-[<instances>Effect Instances|IOEffectInstance|DeferredKEffectInstance|FluxKEffectInstance|MonoKEffectInstance|FlowableKEffectInstance|MaybeKEffectInstance|ObservableKEffectInstance|SingleKEffectInstance]
+[<typeclasses>MonadDefer]<-[<instances>MonadDefer Instances|IOMonadDeferInstance|DeferredKMonadDeferInstance|FluxKMonadDeferInstance|MonoKMonadDeferInstance|FlowableKMonadDeferInstance|MaybeKMonadDeferInstance|ObservableKMonadDeferInstance|SingleKMonadDeferInstance]
 [<typeclasses>Monad]<-[<typeclasses>Bimonad]
 [<typeclasses>Comonad]<-[<typeclasses>Bimonad]
 [<typeclasses>Functor]<-[<typeclasses>Comonad]
-[<typeclasses>Functor]<-[<typeclasses>Traverse]
-[<typeclasses>Foldable]<-[<typeclasses>Traverse]
 [<typeclasses>SemigroupK]<-[<typeclasses>MonoidK]
 [<typeclasses>MonoidK]<-[<instances>MonoidK Instances|ListKMonoidKInstance|OptionTMonoidKInstance|SequenceKMonoidKInstance|SetKMonoidKInstance|WriterTMonoidKInstance]
 [<typeclasses>SemigroupK]<-[<instances>SemigroupK Instances|EitherSemigroupKInstance|ListKSemigroupKInstance|NonEmptyListSemigroupKInstance|OptionTSemigroupKInstance|SequenceKSemigroupKInstance|SetKSemigroupKInstance|StateTSemigroupKInstance|ValidatedSemigroupKInstance|WriterTSemigroupKInstance]
 [<typeclasses>Bimonad]<-[<instances>Bimonad Instances|EvalBimonadInstance|Function0BimonadInstance|IdBimonadInstance|NonEmptyListBimonadInstance]
-[<typeclasses>Foldable]<-[<instances>Foldable Instances|ConstFoldableInstance|EitherFoldableInstance|IdFoldableInstance|OptionFoldableInstance|TryFoldableInstance|Tuple2FoldableInstance|CoproductFoldableInstance|IorFoldableInstance|ListKFoldableInstance|MapKFoldableInstance|NonEmptyListFoldableInstance|OptionTFoldableInstance|SequenceKFoldableInstance|SetKFoldableInstance|SortedMapKFoldableInstance|ValidatedFoldableInstance]
-[<typeclasses>Traverse]<-[<instances>Traverse Instances|ConstTraverseInstance|EitherTraverseInstance|IdTraverseInstance|OptionTraverseInstance|TryTraverseInstance|Tuple2TraverseInstance|CoproductTraverseInstance|IorTraverseInstance|ListKTraverseInstance|MapKTraverseInstance|NonEmptyListTraverseInstance|OptionTTraverseInstance|SequenceKTraverseInstance|SortedMapKTraverseInstance|ValidatedTraverseInstance]
 [<typeclasses>Eq]<-[<instances>Eq Instances|ConstEqInstance|EitherEqInstance|IdEqInstance|OptionEqInstance|TryEqInstance|Tuple10EqInstance|Tuple2EqInstance|Tuple3EqInstance|Tuple4EqInstance|Tuple5EqInstance|Tuple6EqInstance|Tuple7EqInstance|Tuple8EqInstance|Tuple9EqInstance|IorEqInstance|ListKEqInstance|MapKEqInstance|NonEmptyListEqInstance|SequenceKEqInstance|SetKEqInstance|ValidatedEqInstance]
 [<typeclasses>Show]<-[<instances>Show Instances|ConstShowInstance|EitherShowInstance|IdShowInstance|OptionShowInstance|TryShowInstance|Tuple10ShowInstance|Tuple2ShowInstance|Tuple3ShowInstance|Tuple4ShowInstance|Tuple5ShowInstance|Tuple6ShowInstance|Tuple7ShowInstance|Tuple8ShowInstance|Tuple9ShowInstance|IorShowInstance|ListKShowInstance|MapKShowInstance|NonEmptyListShowInstance|SequenceKShowInstance|SetKShowInstance|SortedMapKShowInstance|ValidatedShowInstance]
+[<typeclasses>Monoid]<-[<instances>Monoid Instances|IOMonoidInstance|ConstMonoidInstance|EitherMonoidInstance|OptionMonoidInstance|TryMonoidInstance|Tuple2MonoidInstance|ListKMonoidInstance|MapKMonoidInstance|SequenceKMonoidInstance|SetKMonoidInstance|SortedMapKMonoidInstance]
+[<typeclasses>Semigroup]<-[<instances>Semigroup Instances|IOMonoidInstance|IOSemigroupInstance|ConstSemigroupInstance|EitherSemigroupInstance|OptionSemigroupInstance|TrySemigroupInstance|ListKSemigroupInstance|MapKSemigroupInstance|NonEmptyListSemigroupInstance|SequenceKSemigroupInstance|SetKSemigroupInstance|SortedMapKSemigroupInstance]
+[<typeclasses>Foldable]<-[<instances>Foldable Instances|FluxKFoldableInstance|FlowableKFoldableInstance|MaybeKFoldableInstance|ObservableKFoldableInstance|ConstFoldableInstance|EitherFoldableInstance|IdFoldableInstance|OptionFoldableInstance|TryFoldableInstance|Tuple2FoldableInstance|CoproductFoldableInstance|IorFoldableInstance|ListKFoldableInstance|MapKFoldableInstance|NonEmptyListFoldableInstance|OptionTFoldableInstance|SequenceKFoldableInstance|SetKFoldableInstance|SortedMapKFoldableInstance|ValidatedFoldableInstance]
+[<typeclasses>Traverse]<-[<instances>Traverse Instances|FluxKTraverseInstance|FlowableKTraverseInstance|ObservableKTraverseInstance|ConstTraverseInstance|EitherTraverseInstance|IdTraverseInstance|OptionTraverseInstance|TryTraverseInstance|Tuple2TraverseInstance|CoproductTraverseInstance|IorTraverseInstance|ListKTraverseInstance|MapKTraverseInstance|NonEmptyListTraverseInstance|OptionTTraverseInstance|SequenceKTraverseInstance|SortedMapKTraverseInstance|ValidatedTraverseInstance]
+[<typeclasses>ApplicativeError]<-[<instances>ApplicativeError Instances|IOApplicativeErrorInstance|DeferredKApplicativeErrorInstance|FluxKApplicativeErrorInstance|MonoKApplicativeErrorInstance|FlowableKApplicativeErrorInstance|MaybeKApplicativeErrorInstance|ObservableKApplicativeErrorInstance|SingleKApplicativeErrorInstance|EitherApplicativeErrorInstance|OptionApplicativeErrorInstance|TryApplicativeErrorInstance|KleisliApplicativeErrorInstance|StateTApplicativeErrorInstance|ValidatedApplicativeErrorInstance]
+[<typeclasses>MonadError]<-[<instances>MonadError Instances|IOMonadErrorInstance|DeferredKMonadErrorInstance|FluxKMonadErrorInstance|MonoKMonadErrorInstance|FlowableKMonadErrorInstance|MaybeKMonadErrorInstance|ObservableKMonadErrorInstance|SingleKMonadErrorInstance|EitherMonadErrorInstance|OptionMonadErrorInstance|TryMonadErrorInstance|KleisliMonadErrorInstance|StateTMonadErrorInstance]
 [<typeclasses>Comonad]<-[<instances>Comonad Instances|EvalComonadInstance|Function0ComonadInstance|IdComonadInstance|Tuple2ComonadInstance|CofreeComonadInstance|CoproductComonadInstance|NonEmptyListComonadInstance]
+[<typeclasses>Applicative]<-[<instances>Applicative Instances|IOApplicativeInstance|DeferredKApplicativeInstance|FluxKApplicativeInstance|MonoKApplicativeInstance|FlowableKApplicativeInstance|MaybeKApplicativeInstance|ObservableKApplicativeInstance|SingleKApplicativeInstance|ConstApplicativeInstance|EitherApplicativeInstance|EvalApplicativeInstance|Function0ApplicativeInstance|Function1ApplicativeInstance|IdApplicativeInstance|OptionApplicativeInstance|TryApplicativeInstance|Tuple2ApplicativeInstance|FreeApplicativeApplicativeInstance|FreeApplicativeInstance|IorApplicativeInstance|KleisliApplicativeInstance|ListKApplicativeInstance|NonEmptyListApplicativeInstance|OptionTApplicativeInstance|SequenceKApplicativeInstance|StateTApplicativeInstance|ValidatedApplicativeInstance|WriterTApplicativeInstance]
+[<typeclasses>Monad]<-[<instances>Monad Instances|IOMonadInstance|DeferredKMonadInstance|FluxKMonadInstance|MonoKMonadInstance|FlowableKMonadInstance|MaybeKMonadInstance|ObservableKMonadInstance|SingleKMonadInstance|EitherMonadInstance|EvalMonadInstance|Function0MonadInstance|Function1MonadInstance|IdMonadInstance|OptionMonadInstance|TryMonadInstance|Tuple2MonadInstance|FreeMonadInstance|IorMonadInstance|KleisliMonadInstance|ListKMonadInstance|NonEmptyListMonadInstance|OptionTMonadInstance|SequenceKMonadInstance|StateTMonadInstance|WriterTMonadInstance]
 [<typeclasses>Monad]<-[<typeclasses>MonadReader]
 [<typeclasses>MonadReader]<-[<instances>MonadReader Instances|Function1MonadReaderInstance|KleisliMonadReaderInstance]
 [<typeclasses>Functor]<-[<typeclasses>FunctorFilter]
@@ -57,13 +66,4 @@
 [<typeclasses>Birecursive]<-[<instances>Birecursive Instances|FixBirecursiveInstance|MuBirecursiveInstance|NuBirecursiveInstance]
 [<typeclasses>Corecursive]<-[<instances>Corecursive Instances|FixCorecursiveInstance|MuCorecursiveInstance|NuCorecursiveInstance]
 [<typeclasses>Recursive]<-[<instances>Recursive Instances|FixRecursiveInstance|MuRecursiveInstance|NuRecursiveInstance]
-[<typeclasses>Async]<-[<instances>Async Instances|IOAsyncInstance]
-[<typeclasses>Effect]<-[<instances>Effect Instances|IOEffectInstance]
-[<typeclasses>MonadDefer]<-[<instances>MonadDefer Instances|IOMonadDeferInstance]
-[<typeclasses>ApplicativeError]<-[<instances>ApplicativeError Instances|IOApplicativeErrorInstance|EitherApplicativeErrorInstance|OptionApplicativeErrorInstance|TryApplicativeErrorInstance|KleisliApplicativeErrorInstance|StateTApplicativeErrorInstance|ValidatedApplicativeErrorInstance]
-[<typeclasses>MonadError]<-[<instances>MonadError Instances|IOMonadErrorInstance|EitherMonadErrorInstance|OptionMonadErrorInstance|TryMonadErrorInstance|KleisliMonadErrorInstance|StateTMonadErrorInstance]
-[<typeclasses>Monoid]<-[<instances>Monoid Instances|IOMonoidInstance|ConstMonoidInstance|EitherMonoidInstance|OptionMonoidInstance|TryMonoidInstance|Tuple2MonoidInstance|ListKMonoidInstance|MapKMonoidInstance|SequenceKMonoidInstance|SetKMonoidInstance|SortedMapKMonoidInstance]
-[<typeclasses>Semigroup]<-[<instances>Semigroup Instances|IOMonoidInstance|IOSemigroupInstance|ConstSemigroupInstance|EitherSemigroupInstance|OptionSemigroupInstance|TrySemigroupInstance|ListKSemigroupInstance|MapKSemigroupInstance|NonEmptyListSemigroupInstance|SequenceKSemigroupInstance|SetKSemigroupInstance|SortedMapKSemigroupInstance]
-[<typeclasses>Applicative]<-[<instances>Applicative Instances|IOApplicativeInstance|ConstApplicativeInstance|EitherApplicativeInstance|EvalApplicativeInstance|Function0ApplicativeInstance|Function1ApplicativeInstance|IdApplicativeInstance|OptionApplicativeInstance|TryApplicativeInstance|Tuple2ApplicativeInstance|FreeApplicativeApplicativeInstance|FreeApplicativeInstance|IorApplicativeInstance|KleisliApplicativeInstance|ListKApplicativeInstance|NonEmptyListApplicativeInstance|OptionTApplicativeInstance|SequenceKApplicativeInstance|StateTApplicativeInstance|ValidatedApplicativeInstance|WriterTApplicativeInstance]
-[<typeclasses>Functor]<-[<instances>Functor Instances|IOFunctorInstance|ConstFunctorInstance|EitherFunctorInstance|EvalFunctorInstance|Function0FunctorInstance|Function1FunctorInstance|IdFunctorInstance|OptionFunctorInstance|TryFunctorInstance|Tuple2FunctorInstance|CofreeFunctorInstance|CoyonedaFunctorInstance|FreeApplicativeFunctorInstance|FreeFunctorInstance|YonedaFunctorInstance|CoproductFunctorInstance|IorFunctorInstance|KleisliFunctorInstance|ListKFunctorInstance|MapKFunctorInstance|NonEmptyListFunctorInstance|OptionTFunctorInstance|SequenceKFunctorInstance|SortedMapKFunctorInstance|StateTFunctorInstance|ValidatedFunctorInstance|WriterTFunctorInstance]
-[<typeclasses>Monad]<-[<instances>Monad Instances|IOMonadInstance|EitherMonadInstance|EvalMonadInstance|Function0MonadInstance|Function1MonadInstance|IdMonadInstance|OptionMonadInstance|TryMonadInstance|Tuple2MonadInstance|FreeMonadInstance|IorMonadInstance|KleisliMonadInstance|ListKMonadInstance|NonEmptyListMonadInstance|OptionTMonadInstance|SequenceKMonadInstance|StateTMonadInstance|WriterTMonadInstance]
+[<typeclasses>Functor]<-[<instances>Functor Instances|IOFunctorInstance|DeferredKFunctorInstance|FluxKFunctorInstance|MonoKFunctorInstance|FlowableKFunctorInstance|MaybeKFunctorInstance|ObservableKFunctorInstance|SingleKFunctorInstance|ConstFunctorInstance|EitherFunctorInstance|EvalFunctorInstance|Function0FunctorInstance|Function1FunctorInstance|IdFunctorInstance|OptionFunctorInstance|TryFunctorInstance|Tuple2FunctorInstance|CofreeFunctorInstance|CoyonedaFunctorInstance|FreeApplicativeFunctorInstance|FreeFunctorInstance|YonedaFunctorInstance|CoproductFunctorInstance|IorFunctorInstance|KleisliFunctorInstance|ListKFunctorInstance|MapKFunctorInstance|NonEmptyListFunctorInstance|OptionTFunctorInstance|SequenceKFunctorInstance|SortedMapKFunctorInstance|StateTFunctorInstance|ValidatedFunctorInstance|WriterTFunctorInstance|IntListPatternFunctorInstance]

modules/docs/arrow-docs/docs/_data/menu.yml

@@ -28,6 +28,9 @@ options:
       - title: Dependency Injection
         url: /docs/patterns/dependency_injection/
 
+      - title: The Monad Tutorial
+        url: /docs/patterns/monads/
+
       - title: Monad Comprehensions
         url: /docs/patterns/monad_comprehensions/
 

modules/docs/arrow-docs/docs/docs/README.md

@@ -12,7 +12,10 @@ NOTE: The docs are currently at around 60% completion. They're the present prior
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0)
 
 Λrrow is a library for Typed Functional Programming in Kotlin.
-It includes the most popular data types, type classes and abstractions such as `Option`, `Try`, `Either`, `IO`, `Functor`, `Applicative`, `Monad` to empower users to define pure FP apps and libraries built atop higher order abstractions.
+
+Arrow aims to provide a *lingua franca* of interfaces and abstractions across Kotlin libraries.
+For this, it includes the most popular data types, type classes and abstractions such as `Option`, `Try`, `Either`, `IO`, `Functor`, `Applicative`, `Monad` to empower users to define pure FP apps and libraries built atop higher order abstractions.
+
 Use the list below to learn more about Λrrow's main features.
 
 - [Patterns](http://arrow-kt.io/docs/patterns/glossary/): tutorials and approaches to day-to-day challenges using FP 

modules/docs/arrow-docs/docs/docs/patterns/glossary/README.md

@@ -28,7 +28,7 @@ You can read more about all the [datatypes]({{ '/docs/datatypes/intro' | relativ
 
 ### Typeclasses
 
-Typeclasses define a set of functions associated to one type.
+Typeclasses define a set of extension functions associated to one type.
 This behavior is checked by a test suite called the "laws" for that typeclass.
 
 You can use typeclasses as a DSL to add new free functionality to an existing type
@@ -46,6 +46,9 @@ One example, the typeclass `Eq` parametrized to `F` defines equality between two
 ```kotlin
 interface Eq<F> {
   fun F.eqv(b: F): Boolean
+
+  fun F.neqv(b: F): Boolean =
+    !eqv(b)
 }
 ```
 

modules/docs/arrow-docs/docs/docs/patterns/monadcomprehensions/README.md

@@ -9,7 +9,7 @@ permalink: /docs/patterns/monad_comprehensions/
 {:.intermediate}
 intermediate
 
-Monad comprehension is the name for a programming idiom available in multiple languages.
+Monad comprehension is the name for a programming idiom available in multiple languages like JavaScript, F#, Scala, or Haskell.
 The purpose of monad comprehensions is to compose sequential chains of actions in a style that feels natural for programmers of all backgrounds.
 
 ### Synchronous sequences of actions
@@ -37,12 +37,15 @@ They allow us to write sequenced code that can be run asynchronously over multip
 
 ### Asynchronous sequences of actions
 
-The general representation of sequenced execution in code is called a [`Monad`]({{ '/docs/typeclasses/monad' | relative_url }}). This typeclass is a short API for sequencing code, summarised in a single function `flatMap`.
-It takes as a parameter one function to be called after the current operation completes, and that function has to return another [`Monad`]({{ '/docs/typeclasses/monad' | relative_url }}) to continue the operation with.
-A common renaming of `flatMap` is `andThen`. Go to the documentation page to see a deep dive on the Monad API.
-
+The abstraction of sequencing execution of code is summarised in a single function that in Arrow is called `flatMap`,
+although you may find it in other languages referred as `andThen`, `then`, `bind`, or `SelectMany`.
+It takes as a parameter one function to be called after the current operation completes, and that function has to return another value to continue the operation with.
 With knowledge of `flatMap` we can write sequential expressions that are ran asynchronously, even over multiple threads.
-Implementations of `Monad` are available for internal types like `Try` and also integrations like [RxJava 2]({{ '/docs/integrations/rx2' | relative_url }}) and [kotlinx.coroutines]({{ '/docs/integrations/kotlinxcoroutines' | relative_url }}). 
+
+The [typeclass]({{ '/docs/typeclasses/intro' | relative_url }}) interface that abstracts sequenced execution of code via `flatMap` is called a [`Monad`]({{ '/docs/typeclasses/monad' | relative_url }}),
+for which we also have a [tutorial]({{ '/docs/patterns/monads' | relative_url }}).
+
+Implementations of [`Monad`]({{ '/docs/typeclasses/monad' | relative_url }}) are available for internal types like `Try` and also integrations like [RxJava 2]({{ '/docs/integrations/rx2' | relative_url }}) and [kotlinx.coroutines]({{ '/docs/integrations/kotlinxcoroutines' | relative_url }}).
 Let's see one example using a [`Monad`]({{ '/docs/typeclasses/monad' | relative_url }}) called [`IO`]({{ '/docs/effects/io' | relative_url }}), where we fetch from a database the information about the dean of university some student attends:
 
 ```kotlin