From 76e296997d37cd51744987f1b9d628da230ed609 Mon Sep 17 00:00:00 2001 From: Cody Allen Date: Tue, 7 Jun 2016 09:06:22 -0400 Subject: [PATCH 1/2] Add FAQ section to site This is just a start, and there are some more items that we will probably want to add. The import section probably is really a start to #912, and may end up simply referencing a separate import document, as discussed in #936. But I thought it would be nice to get something out there as an interim resolution. --- docs/src/main/tut/faq.md | 64 +++++++++++++++++++++++++++++ docs/src/site/_layouts/default.html | 9 ++-- docs/src/site/css/custom.css | 3 ++ 3 files changed, 73 insertions(+), 3 deletions(-) create mode 100644 docs/src/main/tut/faq.md diff --git a/docs/src/main/tut/faq.md b/docs/src/main/tut/faq.md new file mode 100644 index 0000000000..aefdcec2a7 --- /dev/null +++ b/docs/src/main/tut/faq.md @@ -0,0 +1,64 @@ +--- +layout: default +title: "FAQ" +section: "faq" +--- +# Frequently Asked Questions + +## What imports do I need? + +The easiest approach to cats imports is to import everything that's commonly needed: + +```tut:silent +import cats._ +import cats.data._ +import cats.implicits._ +``` + +The `cats._` import brings in quite a few [typeclasses](http://typelevel.org/cats/typeclasses.html) (similar to interfaces) such as [Monad](http://typelevel.org/cats/tut/monad.html), [Semigroup](http://typelevel.org/cats/tut/semigroup.html), and [Foldable](http://typelevel.org/cats/tut/foldable.html). Instead of the entire `cats` package, you can import only the types that you need, for example: + +```tut:silent +import cats.Monad +import cats.Semigroup +import cats.Foldable +``` + +The `cats.data._`, import brings in data structures such as [Xor](http://typelevel.org/cats/tut/xor.html), [Validated](http://typelevel.org/cats/tut/validated.html), and [State](http://typelevel.org/cats/tut/state.html). Instead of the entire `cats.data` package, you can import only the types that you need, for example: + +```tut:silent +import cats.data.Xor +import cats.data.Validated +import cats.data.State +``` + +The `cats.implicits._` import does a couple of things. Firstly, it brings in implicit type class instances for standard library types - so after this import you will have `Monad[List]` and `Semigroup[Int]` instances in implicit scope. Secondly, it adds syntax enrichment onto certain types to provide some handy methods, for example: + +```tut:book +// cats adds a toXor method to the standard library's Either +val e: Either[String, Int] = Right(3) +e.toXor + +// cats adds an orEmpty method to the standard library's Option +val o: Option[String] = None +o.orEmpty +``` + +**Note**: if you import `cats.implicits._` (the preferred method), you should _not_ also use imports like `cats.std.syntax._` or `cats.std.either._`. This can result in ambiguous implicit values that cause bewildering compile errors. + +## Why can't the compiler find implicit instances for Future? + +If you have already followed the [imports advice](#what-imports) but are still getting error messages like `could not find implicit value for parameter e: cats.Monad[scala.concurrent.Future]` or `value |+| is not a member of scala.concurrent.Future[Int]`, then make sure that you have an implicit `scala.concurrent.ExecutionContext` in scope. The easiest way to do this is to `import scala.concurrent.ExecutionContext.Implicits.global`, but note that you may want to use a different execution context for your production application. + +## How can I turn my List of `` into a `` of a list? + +It's really common to have a `List` of values with types like `Option`, `Xor`, or `Validated` that you would like to turn "inside out" into an `Option` (or `Xor` or `Validated`) of a `List`. The `sequence`, `sequenceU`, `traverse`, and `traverseU` methods are _really_ handy for this. You can read more about them in the [Traverse documentation]({{ site.baseurl }}/tut/traverse.html). + +## How can I help? + +The cats community welcomes and encourages contributions, even if you are completely new to cats and functional programming. Here are a few ways to help out: + +- Find an undocumented method and write a ScalaDoc entry for it. See [Arrow.scala]({{ site.sources }}/core/src/main/scala/cats/arrow/Arrow.scala) for some examples of ScalaDoc entries that use [sbt-doctest](https://github.com/tkawachi/sbt-doctest). +- Look at the [code coverage report](https://codecov.io/github/typelevel/cats?branch=master), find some untested code, and write a test for it. Even simple helper methods and syntax enrichment should be tested. +- Find an [open issue](https://github.com/typelevel/cats/issues?q=is%3Aopen+is%3Aissue+label%3Aready), leave a comment on it to let people know you are working on it, and submit a pull request. If you are new to cats, you may want to look for items with the [low-hanging-fruit](https://github.com/typelevel/cats/issues?q=is%3Aopen+is%3Aissue+label%3A%22low-hanging+fruit%22) label. + +See the [contributing guide]({{ site.baseurl }}/contributing.html) for more information. diff --git a/docs/src/site/_layouts/default.html b/docs/src/site/_layouts/default.html index fdf9f440f3..f74e423785 100644 --- a/docs/src/site/_layouts/default.html +++ b/docs/src/site/_layouts/default.html @@ -40,9 +40,6 @@

Cats

  • About
    • -
  • - Contributing -
  • Typeclasses
    • @@ -52,6 +49,12 @@

    Cats

  • Resources For Learners
    • +
  • + FAQ +
    • +
  • + Contributing +
  • Colophon
    • diff --git a/docs/src/site/css/custom.css b/docs/src/site/css/custom.css index 566189e84b..f6cf4fd977 100644 --- a/docs/src/site/css/custom.css +++ b/docs/src/site/css/custom.css @@ -264,3 +264,6 @@ hr { margin: 5px 12px; } +h2:hover a:after { + content: 'ยง'; +} \ No newline at end of file From bdd47934b1862f880d0cfaab1b9ce7102630a917 Mon Sep 17 00:00:00 2001 From: Cody Allen Date: Wed, 8 Jun 2016 06:46:06 -0400 Subject: [PATCH 2/2] Fix typo in import section of FAQ --- docs/src/main/tut/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/main/tut/faq.md b/docs/src/main/tut/faq.md index aefdcec2a7..188e011572 100644 --- a/docs/src/main/tut/faq.md +++ b/docs/src/main/tut/faq.md @@ -43,7 +43,7 @@ val o: Option[String] = None o.orEmpty ``` -**Note**: if you import `cats.implicits._` (the preferred method), you should _not_ also use imports like `cats.std.syntax._` or `cats.std.either._`. This can result in ambiguous implicit values that cause bewildering compile errors. +**Note**: if you import `cats.implicits._` (the preferred method), you should _not_ also use imports like `cats.syntax.option._` or `cats.std.either._`. This can result in ambiguous implicit values that cause bewildering compile errors. ## Why can't the compiler find implicit instances for Future?