Document instances of type classes

[chuwy]

I think it would be very nice to have list of instances for which type class is implemented on type class documentation page. For example, on Functor page we can list:

• Option
• List
• Stream
• Future
• Xor
• etc

I like that we have this on Hackage, but for cats this probably should be done manually, (although I think I heard something about support of type classes in scaladoc) to concisely highlight implementation details and just because I doubt this can be autogenerated.

I think this can highly improve approachability in following ways:

• Inductive reasoning. It's just easier to understand new concepts by example. Example instances are what newcomers want to see to draw lines between unconnected at first glance entities
• While some instances like Option and List for Functor are obvious and well-known, some are not (functions). At least they weren't for me
• For people migrating from scalaz or Haskell it is good to know for what instances are implemented and what aren't without looking at code (like in Hackage, again)
• It also can be a good idea to describe how instances are defined. For example it can be not obvious at first glance why haven't with Monad[Option] in optionInstances

[ceedubs]

@chuwy would you consider this to be solved by #1565? The instances aren't listed on the type class page itself, but personally I think that the high-level overview provided by the table might be even more helpful, since it allows you to compare which instances are available for which types.

[chuwy]

Hi @ceedubs,

Yes, that PR covers most I wanted to see.

However, there's one problem - namely it doesn't cover too many type classes (Traverse, Semigroup, Arrow etc) and data types (Future, Kleisli etc). I can take over that table and add everything it misses, but I afraid that would make it bloated and unusable.

So if we think that listing instances (more Hackage-way) on type class page is bad idea and cannot come up with anything better (I cannot) then I'm happy to close this.

[ceedubs]

@chuwy ah, that's a good point. I like the idea of listing instances on the type class page; I'm just concerned about the maintenance. We don't have an automated way to keep it up-to-date, and I suspect that it will be prone to falling out-of-date. It could be useful even if it isn't perfect though.

[chuwy]

@ceedubs getting out-of-date was my concern as well, but I guess that will be not such a problem when cats reach 1.0.

[edmundnoble]

👍 to listing instances on the type class page. Sounds useful.

[kubukoz]

I think it should be possible to find all the instances we define using Scalameta...

Possibly even something like A, Monad[F] => Monad[Kleisli[F, A, ?]].

Do you think it's worth taking a look? I'd gladly try doing a prototype myself, if it sounds like a good idea.

[kailuowang]

@kubukoz sounds a good idea to me.