Docs for Func and AppFunc

core/src/main/scala/cats/data/Func.scala

@@ -31,11 +31,18 @@ import cats.Contravariant
  */
 sealed abstract class Func[F[_], A, B] { self =>
   def run: A => F[B]
+
+  /** 
+    * scala> val f = Func.func((x: Int) => List(x.toString))
+    * val f: cats.data.Func[List,Int,String] = ...
+    * scala> val g = f.map((x: String) => if (x=="0") None else Some(x))
+    * val g: cats.data.Func[List,Int,Option[String]] = ...
+    */
   def map[C](f: B => C)(implicit FF: Functor[F]): Func[F, A, C] =
     Func.func(a => FF.map(self.run(a))(f))
 
   /**
-   * Modify the context `F` using transformation `f`.
+   * Modify the context `F` using (natural) transformation `f`.
    */
   def mapK[G[_]](f: F ~> G): Func[G, A, B] =
     Func.func(a => f(run(a)))
@@ -118,6 +125,10 @@ sealed private[data] trait FuncApplicative[F[_], C] extends Applicative[λ[α =>
 
 /**
  * An implementation of [[Func]] that's specialized to [[Applicative]].
+ * 
+ * As seen in [[https://www.cs.ox.ac.uk/jeremy.gibbons/publications/iterator.pdf The Essence of the Iterator Pattern]]
+ * the Applicative Functor "capture the essence of the ITERATOR pattern"
+ * allowing to traverse and compose Applicative Functors
  */
 sealed abstract class AppFunc[F[_], A, B] extends Func[F, A, B] { self =>
   def F: Applicative[F]

docs/datatypes/func.md

@@ -0,0 +1,78 @@
+# Func
+
+Func is a wrapper around a `run` function `a => F[B]` where F is a functor. Given that, the Func data type is equipped with the known `map` function, and a `mapK` function to apply natural transformations (from a `F` Func get an `G` Func).
+
+The signature: `Func[F[_], A, B]` refers to an `F` functor, `A` source type and `B` target type (`F[B]`).
+
+If you are familiar with `Kleisli` you can recognize it has a similar signature: `Kleisli[F[_], -A, B]` and `Func[F[_], A, B]`. Well yes, `Func` is a less restrictive data type that wraps around functors, and only provides basic methods `run`, `map`, and `mapK`, while `Kleisli` is strong enough to provide composition, flatMap, and more. We will see a more useful data type just next with `AppFunc`. 
+
+## Quick example
+
+```scala mdoc:silent:nest
+import cats.data.{ Func, AppFunc }
+import cats._
+
+val f: Func[List, Int, String] = Func.func((x: Int) => List(x.toString))
+
+val g: Func[List, Int, Option[String]] = f.map((x: String) => if (x=="0") None else Some(x))
+
+val optToList = new (Option ~> List) {
+  def apply[T](opt: Option[T]): List[T] =
+    opt.toList
+}
+
+// We transform the elements of List, of type 
+// Option[String] to List[String]
+g.map(optToList(_))
+// val res0: cats.data.Func[List,Int,List[String]] = ...
+```
+
+
+
+# AppFunc 
+
+AppFunc extends Func to wrap around a special type of functor: Applicative functors.
+
+With applicative functors we can `compose`, form the `product`, and also `traverse` traversable functors
+
+Signature: `AppFunc[F[_], A, B] extends Func[F, A, B]` 
+
+Now, for the reader familiar with `Kleisli`, we find an even more similar data type. `AppFunc` provides compositions of weaker constraint, allowing to compose `AppFunc[F[_], A, B]` with `AppFunc[G[_], C, A]`.   
+## Composition
+
+All of functional programming revolves around composing, and functors cannot be left behind. If we are working with multiple contexts we might want to compose them, for example: we want to `List` things, and discard some (`Option`). 
+
+To achieve this nested context behavior `AppFunc` uses the `Nested` datatype. 
+
+```scala mdoc:silent:nest
+val AppFuncF: AppFunc[Option,Int,Int] = Func.appFunc((i: Int) => if (i==0) None else Some(i))
+
+val AppFuncG: AppFunc[List,Int,Int] = Func.appFunc((o: Int) => {List(o+1)})
+(AppFuncF andThen AppFuncG).run(1) //Nested(Some(List(2)))
+
+(AppFuncF andThen AppFuncG).run(0) //Nested(None)
+// same thing with compose
+
+(AppFuncG compose AppFuncF)
+```
+## Product
+
+Applicative functors, like monads, are closed under product. Cats models this data type as Tuple2k, allowing to form the product of two applicative functors (they can be different!) in one data type. 
+
+For further reading: [hearding cats](http://eed3si9n.com/herding-cats/combining-applicative.html#Product+of+applicative+functions) 
+
+```scala mdoc:silent:nest
+(AppFuncF product AppFuncG).run(1)
+```
+## Traverse
+
+This explained in the implementation of the Applicative trait: [Applicative - Traverse](https://typelevel.org/cats/typeclasses/applicative.html#traverse)
+
+```scala mdoc:silent:nest
+AppFuncF.traverse(List(1,2,3))
+// val res14: Option[List[Int]] = Some(List(1, 2, 3))
+
+AppFuncF.traverse(List(1,2,0))
+//val res15: Option[List[Int]] = None
+```
+