Chatgpt is great at “form”, giving you a structure with plausible sounding text so if you’re using it that way, seems reasonable. It’s not so great at “facts” or at know what is useful/necessary to doc in the first place :)

Indeed, you can't trust what it confidently tells you. You can, however, "prime" it with some data and ask it to make adjustments along the way.

> I guess there is some concern around losing clarity and detail ...and correctness 😉

here’s a cautionary anecdote: https://github.com/orgs/open-policy-agent/discussions/319#discussioncomment-4549176

I think concerns around correctness are a little misplaced in the case of having it help you write docs for your own project. Presumably, as the author of the project, you are able to discern between right and wrong. The idea is to tell it enough about your thing and have it formalize the language and glue it together, not for it to be source of truth which you accept at face value.

I asked ChatGPT to explain some of my most convoluted, uncommented code, a random function or shell script with no context, and was really surprised how well it did. In most cases it even correctly guessed the context where the code was used, though it couldn't really know. With some manual correction I think it would be very helpful for making actual docs.

That's fair, as long as it's something you can confidently check for errors, it seems somewhat useful! At that point I feel like it would be almost as easy to just write the docs myself? But I guess it would at least be faster, especially if it does a good job explaining the code in an order that would work well for readers.

What I'd really like is some AI that will translate release notes into updates to the documentation to keep it in sync!

i can usually understand what a piece of code does, i prefer the documentation to explain to me why the code is needed

chatgpt is unlikely to cover that 🙂

https://github.com/arc53/docsgpt

this is really cool. I remember Alexis giving a great talk on this a year or two ago

Just fell down a rabbit hole following links from that post. Lots of interesting ideas. I'm pretty sure the effect handlers that ship with re-frame, fulcro, and membrane are all accidental algebraic effect systems. I was curious if there were any existing clojure libs for algebraic effects and found https://github.com/brandonbloom/cleff. I'm still fuzzy on some of the ideas, but it's possible that https://github.com/leonoel/missionary, https://github.com/IGJoshua/farolero, and interceptors are also in the same category.

Interceptors aren’t in the same category afaik, but farolero definitely is. Common Lisp has delimited continuations (aka conditions and restarts) and Clojure explicitly opted to not implement them because it doesn’t fit well in the JVM’s execution model. Other attempts include Cloroutine, https://github.com/pangloss/pure-conditioning, and https://github.com/swannodette/delimc.

why aren't interceptors in the same category?

Conditions and restarts allow you to pause execution in the middle of a function, execute some other code, and then resume execution. Interceptors are functions composed in a chain that can alter the evaluation of downstream functions. They don’t allow you to suspend or resume execution. Though perhaps I’m looking at different criteria than you, what seems similar about them to you?

I was comparing interceptors to algebraic effects systems.

> Interceptors are functions composed in a chain that can alter the evaluation of downstream functions. If you can insert "some other code" at the beginning of the remainder of the chain, how is that different from "Conditions and restarts allow you to pause execution in the middle of a function, execute some other code, and then resume execution."?

Imagine a simple effect called helloWorld which, when executed, prints “Hello, world” to the screen. That effect could be issued from anywhere inside a function or even within functions called by that function, that code is a black box to the effect system. All the effect system knows is that when helloWorld is triggered, it does its side effect. How might you implement such an effect as an interceptor? An interceptor can choose whether downstream code is executed, but can’t do things when requested by downstream code, it’s done running by the time the downstream code runs. The important part is that the downstream code is what gets to decide when and where the effect occurs, not the effect system.

> An interceptor can choose whether downstream code is executed, but can’t do things when requested by downstream code I'm not sure I understand what you mean by this. I'm not familiar with all interceptor implementations, but re-frame's interceptors allow you to modify the context and the control flow from within an interceptor. It may be clunky or require a workaround, but it's probably possible to achieve the same result. One of the reasons I labeled these options as "accidental" algebraic effects systems is that they often have similar goals, but these implementations are probably less rigorous and less general.

> How might you implement such an effect as an interceptor? There's probably a re-frame issue that describes a similar problem and a workaround. I'm interested in learning more about these more formal descriptions because I think they could provide a more general and rigorous approach. I was thinking of them in the same category because I think interceptors are being used to try to solve a problem that algebraic effect systems and continuations might be able to solve more cleanly.

I encourage you to try implementing an effect system with interceptors, I think the differences will become clear pretty quickly. Here’s an example to try: An effect handler wraps a function that may or may not trigger an effect. When triggered, the effect pauses execution of the wrapped function, prompts the user for input, and based on that input, either returns execution to the wrapped function or bails and returns to the effect handler. It’d look kind of like this:

(defn wrapped []
  (doseq [x (range 10)]
    (if (= x 3)
      (effect)
      (println "Waiting...")))
  {:error false})

(defn effect-handler []
  (println "Enter an even number")
  (print "> ")
  (let [x (read-line)]
    (cond
      (nil? (parse-long x)) {:error true, :type :not-num}
      (even? (parse-long x)) (continue)
      :else {:error true, :type :not-even})))

(defn wrapper []
  (let [result (handle-effect effect-handler 
                 (wrapped))]
    (prn result)))

Waiting...
Waiting...
Waiting...
Enter an even number
> 

{:error true, :type :not-even}

{:error: true, :type :not-num}

Waiting...
Waiting...
<repeated 4 more times>
{:error false}

My point wasn't that you could replace an effects system with interceptors, it's that I think it might be a good idea to replace interceptors with an effects system. If you look at how interceptors are being used, it seems like it might be possible to switch to an effects system without changing much code while providing more features and making it easier to understand.

Do you think effects systems would be an inappropriate use case for the areas where interceptors are being used?

I think it depends on what you’re using interceptors for. I could see how in certain cases what specific interceptors do could be better accomplished by an effects system, e.g. the classic exception interceptor. In other cases the seem fairly orthogonal, like with Ring’s HTTP-parsing interceptors. I could even see adding effect handlers to the stack by putting them in individual interceptors. I’m not super familiar with the use of interceptors in re-frame though.

Yea, I tend to think of middleware as a separate use case. For an effects system, I'm really just focusing on how re-frame uses interceptors. It's also the same use case as fulcro's mutations, and membrane's handlers.

I'm not familiar with ring's http-parsing interceptors. Is that the same as ring's middleware? Afaik, ring's middleware doesn't allow you to reorder the queue of pending ops or modify the context (eg. what handlers are used for each effect).

Ring does use middleware, I mistyped. Pedestal uses interceptors, but mostly for the same things Ring uses middleware for

Also, it seems like pedestal's queue manipulation example is pretty similar to your challenge, http://pedestal.io/guides/what-is-an-interceptor#_error_handling. Is that on purpose? It seems like if their example just read from standard in, instead of parsing the context, it would be pretty similar to your example, no?

Yeah, that’s an example of the classic “error middleware” I mentioned above. It only solves half of the problem though: while it can interrupt execution and move to a higher point in the stack, the handling code higher in the stack can’t choose to resume execution at the point where the condition was raised. Sure you could work around that by encapsulating the resuming logic and having it be called by the down-stack code, but then the up-stack code doesn’t have full control over how the condition is handled. IIRC what farolero does is store the current set of handlers in a dynamic var, and the function that raises conditions first looks for handlers in the current context, and then if the handler decides to bail it throws a special exception. So while you can build something resembling a condition/restart system in Clojure today, it comes with a bunch of caveats: what if someone accidentally catches your magic exception? Will other devs/tooling recognize your system and e.g. warn when you’re missing a handler? etc. etc. Language support both makes these patterns work more cleanly and pushes the community to coalesce around the approach and build tooling for it.

Nice! I remember seeing Alexis' talk when this work was announced. Does this mean that we'll finally see the completion of the eff library? I lost touch with the effect libraries efforts in the haskell community, how did the situation progress?

https://twitter.com/lexi_lambda/status/1610468254157258753?s=20&t=4u_ziK1EcggIVzP_yJZ_1Q

Thank you @U7RJTCH6J!

I think that re-frame effects and algebraic effects might be solving similar problems but they are quite different in what capabilities they have in terms of code structured & semantics. the reason that effects require delimited continuations is because the fundamental thing that they provide is the ability to mutate the execution of a program.

algebraic effects also give you the ability to observe and simulate the execution of a program

which is also a shared goal with projects like https://github.com/day8/re-frame-10x

I think https://github.com/day8/re-frame/issues/639 is a good example of a current re-frame issue where it might be interesting to compare re-frame effects with a hypothetical algebraic effect option.

I'm not really sure how that issue is interesting re: algebraic effects. Algebraic effects are ordered like any other code you might write; re-frame is just weird because they initially chose to represent side effect data as a map of keys