Documentation: Detailed Introduction to all Effects

[samuelpilz]

As I can see, there is no documentation that presents the effects implemented in this package in Detail and presents usages. Sure, there is an Example module but I did not learn anything from that.

Currently, learning extensible-effects is only possible if one already understands MTL. The goal is to make this package more approachable.

I would like to add:

• [x] more comprehensive package description
  • currently this is a single bullet point of advantages and some limitations)
  • The package description should contain at least some
  • [ ] Explanation of extensions needed to overcome class-constraint warnings at end of Tips and tricks section
  • [ ] Other effects
  • [ ] Integration with Monad Transformers
• [x] A tutorial- or quickstart- module similar to tutorials of other packages.
• [ ] A conclusive List of the effects implemented and their implementations, However, I have not decided where to put that (this is completely missing).
• [ ] A guide on how to implement a custom effect (this is extensible-effects after all :smile:), but this should not be too visible for newcommers (Writing your own Effects and Handlers in README.md)

However, this will take several weeks to do on my part. Are regular status-updates desired? Feedback and reviews are welcome. (my wording is not always the best)

I have good understanding of the basic effects State, Writer, Reader. But have problems for others.

I get the intent of Trace and Fresh, but do not get why it is implemented in the way it is. I have ideas about Choose and NdetEff but what is the difference? It says "Another implementation of nondeterministic choice effect" in the documentation, but an explanation, is missing what is different.

I absolutely do not get the Cut, Coroutine and Operational effects, but will have a deeper look into them.

@suhailshergill are there any other resources for the effects that you could link to? Or could you explain some design decisions made for the API?

[suhailshergill]

@power-fungus first off, i love love love the idea and fully support it :grinning: second, it might be useful for you to go through http://okmij.org/ftp/Computation/having-effect.html (and perhaps incorporate some of that in your guide). third, this will be a bit of work, and in order to get it right, it will require multiple review cycles. here is my proposal: open a PR almost immediately with some focused thoughts. commit and push often, and it will make it manageable for me to review and/or even submit patches to your PR(s). if you wait to open the PR till the end, the review will take far too long and may require more work on your part.

thoughts?

[suhailshergill]

oh and regarding the effects like Cut, Coroutine and Operational. Let's get to them bit by bit. The paper describes some (for Cut and Coroutine) and Operational is described in operational package

[samuelpilz]

I am in favor of a tight review cycle and will try to start soon. The descrption of the more "standard" effects will be first.

[samuelpilz]

I want to start the documentation with the selling points of extensible-effects. Obviously, "read this paper and read that paper" is not a good introduction to any library although in widespread use (anyone coming to the library wants to use it, not have an idea how and why it is implemented).

For that, I want to list and describe the main selling points. I have some listed by myself but this needs further input (independent from my list). For that:

• What does this library? What would it be used for?
• What does it better than other similar ones?

[suhailshergill]

@power-fungus let's review the ones you have in a PR. it will be easier to add to that list

[suhailshergill]

@power-fungus let me know which effects you'd like to tackle next and/or if there are some effects you'd like to go over/discuss.

[samuelpilz]

@suhailshergill I am currently working on the QuickStart module. However, I ab quite busy the last weeks.

[suhailshergill]

Will try and devote some time to this in the next couple of weeks.

[suhailshergill]

@greydot i took some time to outline the current steps (4d834cc) when implementing a custom effect. this might help you with documentation. please tweak as desired (consider this merely a first draft). let me know in case there are any questions.

[greydot]

@suhailshergill why a new effect for this tutorial, btw? I think Fresh is written specifically for that. If not, maybe it sould be removed? I don't think anyone would use it given there is State.

[suhailshergill]

You're correct; good catch! No reason other than my forgetfulness. Would you like to make the tweaks, or prefer of I do instead?

-- Suhail

On Mon, 11 Mar 2019, 19:58 Lana Black, [email protected] wrote:

@suhailshergill https://github.com/suhailshergill why a new effect for this tutorial, btw? I think Fresh is written specifically for that. If not, maybe it sould be removed? I don't think anyone would use it given there is State.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/suhailshergill/extensible-effects/issues/99#issuecomment-471788861, or mute the thread https://github.com/notifications/unsubscribe-auth/AA0qpiadQ8TRqzpbJbKsStIwu2Y4t7Dxks5vVu3AgaJpZM4TdQEw .

[greydot]

@suhailshergill I'll do that since I'm already working on it. I'm going to expand your example first, then we'll deal with Fresh.

[suhailshergill]

@greydot let me know if i can be of any assistance in either resolving this issue or the impending release on hackage.

[greydot]

@suhailshergill again, sorry for the delay. I'm overwhelmed with work here.

I decided to move the tutorial to a separate repo because of extra deps. Extensible-effects has no business depending on containers, for one, but Map is really useful in a demo.

The repo is here. I promise I will take a vacation and finish the tutorial some time soon.

Meanwhile, I suppose you can make a release without a tutorial now if you want.

[suhailshergill]

@greydot i am a fan of keeping dependencies small however i do also think it important for tutorials to be closely tied to the associated codebase. we could have the tutorial be a separate module and part of an independent build target as a compromise perhaps?

on a related note, the current tutorial doesn't have a containers dependency (however the one you linked does). could you elaborate on the motivation for the changes (and additional complexity)? was the current example too trivial?

[greydot]

@suhailshergill good point. I'll move the code into the main repo.

I would like to make the tutorial cover the real-life use cases. That's why all the fuzz.