Document instances of type classes
Nobody has claimed this yet.
- Dominant language
- Scala
- Stars
- 5.5k
- Forks
- 1.2k
- Avg merge
- 2d 10h
- Merged PRs (30d)
- 5
Description
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:
OptionListStreamFutureXor- 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
OptionandListforFunctorare 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]inoptionInstances
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the Functor documentation page linked in the issue and inspect the other type-class documentation pages for their current structure. Determine which implemented instances should be listed and how instance definitions should be described; done means the relevant documentation consistently presents this information without relying on undocumented assumptions about generated scaladoc.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- scala
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100