Confusion about Instances{peano}: document reasoning behind Instances0, Instances1, ..

[aaronlevin]

I submitted my first, albeit small PR just now. One thing that confused me was the presence of traits like: XInstances0, XInstances1, XInstances2, etc. I understand the existence of XInstances but why are they spread over the naturals like that?

This gave me a little anxiety when I was submitting my first PR because I wanted to ensure I put my first instance in the right place. I have no idea where my instance resides in the peano hierarchy of random instances, nor, given my scala experience, could I infer why things were designed this way.

Suggestions:

• somewhere in documentation (or contributing guidelines) give historical reasoning for this design choice.
• in same documentation give simple criteria for how to determine which peano trait to place your instance.

I hope that's clear. Also, I'm so curious to find out the history behind this!

[ceedubs]

@aaronlevin thank you for bringing this up. I agree that we need to properly document this (probably in the contributing guidelines, because end-users shouldn't have to worry about it).

This is exactly the sort of thing that I was referencing in #996 (comment) :). I don't have time to put together proper documentation for this this week. A quick example I can point to is #538. Before that (once I switch around the order of the type parameters to match the order they are in now), implicit def oneAndFunctor[F[_]](implicit F: Functor[F]): Functor[OneAnd[F, ?]] and implicit def oneAndMonad[F[_]](implicit monad: MonadCombine[F]): Monad[OneAnd[F, ?]] were defined in the same trait OneAndInstances. If you tried to fetch the implicit Functor[NonEmptyList] instance, you would get the ambiguous implicit values message pasted at the top of that issue. By using a subtyping relationship within the InstanceX hierarchy you can prioritize one of those instances to avoid ambiguity. #963 suggests an encoding of typeclasses where Functor wouldn't actually be a subtype of MonadCombine and this shouldn't be a problem, but there are tradeoffs.

[aaronlevin]

@ceedubs oh, wow, thanks for the explanation! I am happy to try and write something up if you can point me to where in the docs this would go!

[ceedubs]

@aaronlevin thank you for volunteering to write something. Sorry that I didn't get back to you for a while. My delay was because I'm not sure exactly what to say. For a long time we have had this TODO in the contributor guide. I don't like the idea of having a humongous contributor guide that might be intimidating for new contributors. But I also don't want to leave people guessing or send them down too many separate links. Maybe we could have that part of the contributing guide link to a reference document describing detailed code conventions? I'm really open to ideas here.

[ceedubs]

@aaronlevin I'm coming back to this ancient issue. There is now a bit of information about this in the guidelines doc. What do you think? Should we close this issue out or do you think that the info should be more detailed?