Imports section #936
Imports section #936
Conversation
Placement suggested in typelevel#912
Current coverage is
|
|
|
||
| * ``import cats.std.<type>._ `` - Typeclass instances for standard library `<type>`, such as `List` or `Option` | ||
| * ``import cats.syntax.<type>._ `` - “Enhanced” methods for a givent `<type>`, such as calling `.left` to get a left `Xor` | ||
| * ``import cats.data.<type>._ `` - Imports a `<type>` not part of the standard library, such as `Xor`, `Kleisli`), _and its typeclass instances_ |
There was a problem hiding this comment.
I may be fussing about the details a bit too much here, but I think we might want to change this a bit for clarity. If you want to import Xor, you need to import cats.data.Xor, not cats.data.Xor._.
And technically the typeclass instances for cats.data.<type> are in scope whether you import cats.data.<type>._ or not since they are in the relevant companion objects. As an example, you can open up a fresh console with Cats on the classpath and without any imports do:
scala> implicitly[cats.functor.Bifunctor[cats.data.Xor]]
res1: cats.functor.Bifunctor[cats.data.Xor] = cats.data.XorInstances$$anon$3@7ebe767cSo maybe we want to change this to something a little simpler like:
``import cats.data.<type>`` - Imports a `<type>` not part of the standard library (such as `Xor`, `Kleisli`)What do you think? If we are doing that, we might want to provide a similar line for type classes, which wouldn't be under .data.
|
Thanks, @noelmarkham! I'm definitely glad to see this being introduced to the docs. I've left a couple thoughts. |
|
@noelmarkham questions about imports seem to come up all the time. I think it's really time we get some help along this line published. I'd like to see a dedicated import documentation page with some tut examples of various examples and which imports they would require. Do you have any interest in expanding your work on this, or would you prefer for me to give that a try in a separate PR? |
|
I'd love to spend some time on this. I'm sorry this PR has been quiet for so long - I'm going to to try and get it tidied up this week, and yes, I'd be more than happy to get involved in some better documentation around a dedicated import page. I'll pop into the gitter channel sometime this week to talk more about this. Thanks! |
|
@noelmarkham sounds great. Thanks! |
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 typelevel#912, and may end up simply referencing a separate import document, as discussed in typelevel#936. But I thought it would be nice to get something out there as an interim resolution.
|
@noelmarkham I think I'm going to go ahead and start on a more detailed import guide. I hope that you don't mind. Questions come up pretty often, and I'm trying to knock out the items that I think that we need before a 1.0 release. |
|
This PR has been stale for a while, and an import guide has been added in the meantime, so I'm going to go ahead and close it out. One thing that the import guide doesn't include is a guide on piecemeal imports, so I've created #1668 to track that. |
Placement suggested in #912