typelevel / typelevel/cats

Document instances of type classes

Open
#1,287 7 comments 0 reactions 0 assignees View on GitHub

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:

  • 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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.