Export lists for modules

[gabrielhdt]

The API of Cooked-validators is difficult to understand because everything is exported. Take for instance the module Cooked.Tweak.Common. It exposes

• a Tweak monad (called MonadTweak) whose methods are get and put renamed into getTxSkel and putTxSkel,
• a Tweak type which is an alias of StateT .... There is in appearance no reason to create a custom type class MonadTweak, and users cannot guess whether their functions should be

  foo :: MonadTweak m => ... -> m a

  or

  foo :: Monad m => ... -> Tweak m a

The MonadTweak is provided as the suitable abstraction (the StateT alias may change over time). Therefore, the module should export only MonadTweak, not Tweak.

This mechanism should be extended to the whole codebase, in order to make the API of Cooked explicit.

[florentc]

I think we should first only consider the export lists question. And after it is settled, whether we qualify cooked modules internally (and how), or not (this could be some future v3 API-refactoring work).

Regarding the export lists, there are several alternatives I think:

• Export everything (like right now)
• Have explicit export lists in every individual module
• Compromise: only have export list in the re-export modules such as Cooked, Cooked.MockChain, Cooked.Attack, Cooked.Pretty, and Cooked.Tweak. I think it is nice to have a Cooked that exports everything a user needs so that they only have to import qualified Cooked. If they need something very specific they can import it in addition to Cooked from the relevant leaf module import qualified Cooked.This.That as Cooked (foo, bar).

[gabrielhdt]

Aah I didn't mean to talk about qualification, sorry, I meant exporting the monad (which happens to be called MonadTweak) vs exporting the type alias (which happens to be called Tweak)! The qualification has its own issue #279.

[gabrielhdt]

For your third proposition, IMO having export lists will also help us modularising properly the code.

[carlhammann]

1. I'm all for export lists in cooked.
2. I also like the idea of having some modules with carefully curated export lists and some "internal" modules without export lists. For example:
   • Modules like Cooked.MockChain.Balancing and Cooked.MockChain.GenerateTx contain nothing that a user should ever have to use, but everything they define is used somewhere internally. So, these module do not really need an explicit export list in my opinion.
   • Modules like Cooked.Tweak.Common will probably have to be split in two, if we don't go the "re-exporting modules with export list" route @florentc proposes. The fact is that we must export MonadTweak, because it is the intended interface, but we must also export (some functions that operate on Tweak), because that's what the implementation of Cooked.MockChain.Staged uses.

[gabrielhdt]

In any case, having some modules with precise export list is something we apparently all agree on, so we can settle on that, and discuss the other modules later.

[florentc]

Aah I didn't mean to talk about qualification, sorry, I meant exporting the monad (which happens to be called MonadTweak) vs exporting the type alias (which happens to be called Tweak)! The qualification has its own issue #279.

Oh my bad, I mixed up the two issues