Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Imports section #936

Closed
wants to merge 1 commit into from
Closed

Imports section #936

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions docs/src/site/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,14 @@ In an attempt to be more modular, Cats is broken up into a number of sub-project
* *tests* - tests that check type class instances with laws from *laws*
* *docs* - The source for this website

## Imports

It should be sufficient to simply `import cats.implicits._`. However, if you wish to be more specific, use the following rules to get started on what to import:

* ``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`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It may be worth specifically mentioning the syntax provided by cats.syntax.std.<type>._ since this is probably commonly used for Option syntax etc.

* ``import cats.data.<type>._ `` - Imports a `<type>` not part of the standard library, such as `Xor`, `Kleisli`), _and its typeclass instances_
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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@7ebe767c

So 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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like this change.


<a name="copyright"></a>
# Copyright and License

Expand Down