Maintain Traverse and TraverseFilter documents (#122)

* Maintain `Traverse` and `TraverseFilter` documents

* Modify a sentence

Author: hadilq

arrow-libs/core/arrow-core-data/src/main/kotlin/arrow/typeclasses/Traverse.kt

@@ -528,13 +528,13 @@ import arrow.core.ValidatedNel
 interface Traverse<F> : Functor<F>, Foldable<F> {
 
   /**
-   * Given a function which returns a G effect, thread this effect through the running of this function on all the
-   * values in F, returning an F<B> in a G context.
+   * Given a function which returns a [G] effect, thread this effect through the running of this function on all the
+   * values in [F], returning an [F]<[B]> in a [G] context.
    */
   fun <G, A, B> Kind<F, A>.traverse(AP: Applicative<G>, f: (A) -> Kind<G, B>): Kind<G, Kind<F, B>>
 
   /**
-   * Thread all the G effects through the F structure to invert the structure from F<G<A>> to G<F<A>>.
+   * Thread all the [G] effects through the [F] structure to invert the structure from [F]<[G]<[A]>> to [G]<[F]<[A]>>.
    */
   fun <G, A> Kind<F, Kind<G, A>>.sequence(AG: Applicative<G>): Kind<G, Kind<F, A>> = traverse(AG, ::identity)
 

arrow-libs/core/arrow-core-data/src/main/kotlin/arrow/typeclasses/TraverseFilter.kt

@@ -26,11 +26,18 @@ interface TraverseFilter<F> : Traverse<F>, FunctorFilter<F> {
       Id.just(a)
   }
 
+  /**
+   * Returns [F]<[B]> in [G] context by applying [AP] on a selector function [f], which returns [Option] of [B]
+   * in [G] context.
+   */
   fun <G, A, B> Kind<F, A>.traverseFilter(AP: Applicative<G>, f: (A) -> Kind<G, Option<B>>): Kind<G, Kind<F, B>>
 
   override fun <A, B> Kind<F, A>.filterMap(f: (A) -> Option<B>): Kind<F, B> =
     traverseFilter(IdApplicative) { Id(f(it)) }.value()
 
+  /**
+   * Returns [F]<[A]> in [G] context by applying [GA] on a selector function [f] in [G] context.
+   */
   fun <G, A> Kind<F, A>.filterA(f: (A) -> Kind<G, Boolean>, GA: Applicative<G>): Kind<G, Kind<F, A>> = GA.run {
     traverseFilter(this) { a -> f(a).map { b -> if (b) Some(a) else None } }
   }

arrow-libs/core/arrow-docs/docs/arrow/typeclasses/functor/README.md

@@ -114,4 +114,4 @@ since they are all subtypes of `Functor`
 ank_macro_hierarchy(arrow.typeclasses.Functor)
 
 [functor_source]: https://github.com/arrow-kt/arrow-core/blob/master/arrow-core-data/src/main/kotlin/arrow/typeclasses/Functor.kt
-[functor_laws_source]: https://github.com/arrow-kt/arrow-core/blob/master/arrow-core-test/src/main/kotlin/arrow/test/laws/FunctorLaws.kt
+[functor_laws_source]: https://github.com/arrow-kt/arrow-core/blob/master/arrow-core-test/src/main/kotlin/arrow/core/test/laws/FunctorLaws.kt

arrow-libs/core/arrow-docs/docs/arrow/typeclasses/traverse/README.md

@@ -0,0 +1,67 @@
+---
+layout: docs-core
+title: Traverse
+permalink: /arrow/typeclasses/traverse/
+---
+
+## Traverse
+
+
+
+
+The `Traverse` typeclass is allowing to commute types from `F<G<A>>` to `G<F<A>>` over sequential execution of code.
+The main use of this is traversal over a structure with an effect.
+This doc focuses on the methods provided by the typeclass.
+
+### Main Combinators
+
+`Traverse` includes all combinators present in [`Functor`]({{ '/arrow/typeclasses/functor/' | relative_url }})
+and [`Foldable`]({{ '/arrow/typeclasses/foldable/' | relative_url }}).
+
+#### Kind<F, A>#traverse
+
+Given a function which returns a `G` effect, thread this effect through the running of this function on all the values
+in `F`, returning an `F<B>` in a `G` context.
+
+```kotlin:ank
+import arrow.core.*
+import arrow.core.extensions.id.applicative.applicative
+import arrow.core.extensions.traverse
+
+Some(1).traverse(Id.applicative()) { Id.just(it * 2) }
+```
+
+#### Kind<F, Kind<G, A>>#sequence
+
+Thread all the `G` effects through the `F` structure to invert the structure from `F<G<A>>` to `G<F<A>>`.
+
+```kotlin:ank
+import arrow.core.*
+import arrow.core.extensions.id.applicative.applicative
+
+Const<Int, Nothing>(1).sequence<Nothing, Int, ForId>(Id.applicative())
+```
+
+### Laws
+
+Arrow provides [`TraverseLaws`][travers_laws_source]{:target="_blank"} in the form of test cases for internal verification of lawful instances and third party apps creating their own `Traverse` instances.
+
+#### Creating your own `Traverse` instances
+
+Arrow already provides `Traverse` instances for most common datatypes both in Arrow and the Kotlin stdlib.
+Oftentimes, you may find the need to provide your own for unsupported datatypes.
+
+See [Deriving and creating custom typeclass]({{ '/patterns/glossary' | relative_url }})
+
+### Data types
+
+```kotlin:ank:replace
+import arrow.reflect.*
+import arrow.typeclasses.Traverse
+
+TypeClass(Traverse::class).dtMarkdownList()
+```
+
+ank_macro_hierarchy(arrow.typeclasses.Traverse)
+
+[travers_laws_source]: https://github.com/arrow-kt/arrow-core/blob/master/arrow-core-test/src/main/kotlin/arrow/core/test/laws/TraverseLaws.kt

arrow-libs/core/arrow-docs/docs/arrow/typeclasses/traversefilter/README.md

@@ -9,8 +9,49 @@ permalink: /arrow/typeclasses/traversefilter/
 
 
 
-TODO. Meanwhile you can find a short description in the [intro to typeclasses]({{ '/typeclasses/intro/' | relative_url }}).
+`TraverseFilter` is helpful when you want to combine `Traverse` and `FunctorFilter` as one combined operation.
+This doc focuses on the methods provided by the typeclass.
 
+### Main Combinators
+
+`TraverseFilter` includes all combinators present in [`Traverse`]({{ '/arrow/typeclasses/traverse/' | relative_url }})
+and [`FunctorFilter`]({{ '/arrow/typeclasses/functorfilter/' | relative_url }}).
+
+#### Kind<F, A>#traverseFilter
+
+Returns `F<B>` in `G` context by applying `AP` on a selector function `f`, which returns `Option` of `B` in `G` context.
+
+```kotlin:ank
+import arrow.core.*
+import arrow.core.extensions.id.applicative.applicative
+import arrow.core.extensions.traverseFilter
+
+Some(1).traverseFilter(Id.applicative()) { Id.just(None) }
+Some(1).traverseFilter(Id.applicative()) { Id.just((it * 2).some()) }
+```
+
+#### Kind<F, A>#filterA
+
+Returns `F<A>` in `G` context by applying `GA` on a selector function `f` in `G` context.
+
+```kotlin:ank
+import arrow.core.*
+import arrow.core.extensions.id.applicative.applicative
+import arrow.core.extensions.option.traverseFilter.filterA
+
+Some(1).filterA({ Id.just(false) }, Id.applicative())
+```
+
+### Laws
+
+Arrow provides [`TraverseFilterLaws`][travers_filter_laws_source]{:target="_blank"} in the form of test cases for internal verification of lawful instances and third party apps creating their own `TraverseFilter` instances.
+
+#### Creating your own `TraverseFilter` instances
+
+Arrow already provides `TraverseFilter` instances for most common datatypes both in Arrow and the Kotlin stdlib.
+Oftentimes, you may find the need to provide your own for unsupported datatypes.
+
+See [Deriving and creating custom typeclass]({{ '/patterns/glossary' | relative_url }})
 
 ### Data types
 
@@ -22,3 +63,5 @@ TypeClass(TraverseFilter::class).dtMarkdownList()
 ```
 
 ank_macro_hierarchy(arrow.typeclasses.TraverseFilter)
+
+[travers_filter_laws_source]: https://github.com/arrow-kt/arrow-core/blob/master/arrow-core-test/src/main/kotlin/arrow/core/test/laws/TraverseFilterLaws.kt