search

commercialhaskell / rio

A standard library for Haskell
Other
835 stars 54 forks source link

Documentation Improvements #163

Closed lehins closed 5 years ago

lehins commented 5 years ago

This PR contains a few things, but the major goal is documentation improvements raised in #161

NOTE - It is ready to be merged (modulo the commit squashing), but it is WIP because I'd like to get some feedback on it.

There is a live version of the hadock generated from this PR, which is available here: https://lehins.net/rio/

Few things happed in this PR:

One of the biggest issues I have with current RIO module and in fact even with usual Prelude is that those pages are huge. They take very long time to load and it takes ages to scroll through to find anything on them. All this is due to type classes and the list of all instances for each type. It looks like the situation might get improved with future haddock version: haskell/haddock#1007 but as of now that feature is not yet available. Even with all collapsed instances by default, it will still take forever to load a page with that amount of instances on it. For RIO it is especially a problem, since it brings quite a few libraries together, it makes such common classes as Eq, Show, etc. contain a list of instances that are pages and pages long.

The very nice solution IMHO to the above problem is to keep all of the types and type classes on their own page, while separating all of the functions in their own module. Even the functions that are part of the classes (eg. fmap in Functor) will not be exported together with the class itself. See this solution in action:

One other important (possibly breaking) change included in this PR is the MonadFail export. Namely the fail method from Control.Monad.Monad is no longer exported. According to the original proposal, that method will be removed in the next major version of GHC-8.6, so I though it be a good time to prepare RIO for that change.

lehins commented 5 years ago

I think this PR also addresses #61