Enrich return type for Representable.apply and add doctests

[ceedubs]

The Representable.apply method was discarding information about its
return type in a way that made it not very helpful for some use-cases. I
believe that the change that I made to it makes it strictly more useful
in a compatible way, but let me know if that doesn't seem to be the
case.

While creating this I noticed that our Representable instance for Tuple2
uses true for the first index and false for the second index. I'm not
familiar with any precedents in this area, but I would have expected
false = 0 index and true = 1 index. I assume that this is intended?

I also added several scaladoc examples, because why not?!

[ceedubs]

@eli-jordan would you be willing to take a look at this and let us know your thoughts?

[codecov-io]

Codecov Report

Merging #2426 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #2426   +/-   ##
=======================================
  Coverage   95.22%   95.22%           
=======================================
  Files         351      351           
  Lines        6368     6368           
  Branches      279      276    -3     
=======================================
  Hits         6064     6064           
  Misses        304      304

Impacted Files	Coverage Δ
core/src/main/scala/cats/Representable.scala	100% <ø> (ø)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 84e9641...1c7aac8. Read the comment docs.

[eli-jordan]

@ceedubs The change looks good to me. Thanks for adding the doc tests, I probably should have done that originally :-/

Regarding the instance for Tuple2 using true for the left element and false for the right element. This was an arbitrary decision - Representable just mandates there is a "slot" for every inhabitant of the type. I don't have a strong opinion on whether it should be (true, false) of (false, true)

[ceedubs]

Thanks for the prompt response @eli-jordan. As you said, ultimately the slot assignments for true/false are arbitrary; and I think that changing them at this point would be unnecessarily breaking. Probably best to leave it as it is.

[kailuowang]

Thanks!

[LukaJCB]

LGTM, Thanks! :)