cats icon indicating copy to clipboard operation
cats copied to clipboard

Documentation refresh for monad transformers

Open reardonj opened this issue 9 months ago • 2 comments

This PR came out of a discussion in the Typelevel discord with @djspiewak and @armanbilge regarding unexpected interactions with monad transformers and Cats Effect.

This PR moves around monad transformer documentation to better reflect that it is a more advanced topic:

  • updates the monad transformer documentation
    • to move the overview to a separate section instead of the jump start guide
    • change uses of Future to Try to avoid suggesting developers use the deprecated Future instances
    • add a Pitfalls section to warn users about unfortunate interactions with CE and direct users to Cats MTL as an alternative.
  • moves the Monad Transformer documentation pages out of Data Types to their own section.

I also made a few related changes for consistency:

  • remove the pointless Datatypes index pages that just listed all the datatype page links
  • move the Typeclass page to and Overview page under the Typeclasses section.
  • fix a broken link in guidelines.md

image image

reardonj avatar Mar 04 '25 02:03 reardonj

To minimize these pitfalls, monad transformers should only be used as locally-scoped utilities to reduce boilerplate. Do not include monad transformers in public method signatures. Calling code can always use monad transformers themselves.

@typelevel/cats Anyone strongly disagree with this advice?

This PR has a somewhat large diff, but the focus of it is calling out this often repeated advice (and less examples with Future, and calling out more gotchas).

valencik avatar Mar 08 '25 22:03 valencik

I should perhaps note, "strongly disagree" isn't the only option 😆 Adding more nuance is totally good too!

valencik avatar Mar 08 '25 22:03 valencik