Inconsistent naming of monad transformer functions

[turion]

Most monad transformers have the following pattern: https://github.com/tweag/monad-bayes/blob/110e040099d7f1dc1c5f0bd6170fed759897a5b6/src/Control/Monad/Bayes/Weighted.hs#L48

There are two functions that interpret/run/destruct a transformer FooT, one called foo and runFoo. This is an unusual convention. The most common convention, as far as I'm aware, is the following:

• Call the full transformer FooT
• Declare it as a newtype record, and call the record accessor function runFooT, getFooT or unFooT:

  newtype FooT m a = FooT { runFooT :: m (frobnicate a) }

• Possibly declare an interpretation function runFooT, execFooT, ...
• Declare a type synonym type Foo a = FooT Identity a
• Write a constructor foo :: frobnicate a -> Foo a that is analogous to FooT
• Write a destructor runFoo :: Foo a -> frobnicate a analogous to runFooT

That way, the runFoo functions have the role of destructors, while the foo functions are constructors.

The constructor function for Weighted, coincidentally is called withWeight:

https://github.com/tweag/monad-bayes/blob/110e040099d7f1dc1c5f0bd6170fed759897a5b6/src/Control/Monad/Bayes/Weighted.hs#L65

From that function name, I wouldn't expect a constructor, but rather a function that applies a transformation staying inside the monad.

The question is whether we want to pull these conventions straight. It would cause breakage and trigger a major version release.

[turion]

Note also https://github.com/tweag/monad-bayes/issues/189 which addresses the first step of the inconsistency, and the corresponding PR: https://github.com/tweag/monad-bayes/pull/196#discussion_r973684891. If we're doing this as well, maybe we can do both steps in one go, to concentrate the breakage in one release.

[reubenharry]

I think breakage isn't a big concern. I'd imagine anyone using the package is using the GHC 8 version anyway, which was before another breaking release.

I concur re the naming.

Would be nice to update the tutorials, docs and notebooks if there are name changes.

[turion]

Ok, I'll look into this in my next Haskell week.

[turion]

Would be nice to update the tutorials, docs and notebooks if there are name changes.

Are they in any way tested?

[reubenharry]

Would be nice to update the tutorials, docs and notebooks if there are name changes.

Are they in any way tested?

They are not tested in any way. I looked into using tintin, which makes docs with compiled in-line code, but it was a bit flaky. If it were possible to do the same with Mkdocs, I think it would be fantastic (and would make writing Haskell docs a lot easier for everyone) but I don't know an easy way.

[reubenharry]

Probably there's some way to run the notebooks on CI, but I don't know what it is.

[turion]

Would be nice to update the tutorials, docs and notebooks if there are name changes.

Are they in any way tested?

They are not tested in any way. I looked into using tintin, which makes docs with compiled in-line code, but it was a bit flaky. If it were possible to do the same with Mkdocs, I think it would be fantastic (and would make writing Haskell docs a lot easier for everyone) but I don't know an easy way.

We could try looking at tintin together. Another possibility is also to use markdown-unlit and then compile the markdowns as literate haskell files.

[reubenharry]

That second possibility sounds like the most appealing one to me. I think tintin is doing roughly that anyway, but I'd rather keep MkDocs Material.