Document reaction, make-reaction, and run!

[danielcompton]

There are no docstrings for reagent.ratom/reaction, or make-reaction. It would be really helpful to explain:

• The parameters to make-reaction
• How to use reaction
• How reaction differs from run! and when to use each.

Relates to #116.

[GetContented]

The function make-reaction, and its macro reaction are used to create a Reaction, which is a type that belongs to a number of protocols such as IWatchable, IAtom, IReactiveAtom, IDeref, IReset, ISwap, IRunnable, etc. which make it atom-like: ie it can be watched, derefed, reset, swapped on, and additionally, tracks its derefs, behave reactively, and so on.

Reactions are what give r/atom, r/cursor, and function r/cursor and r/wrap their power.

make-reaction takes one argument, f, and an optional options map. f is the function that the reaction you want to make wraps. the options hash can contain an auto-run boolean (if it should automatically run its function on change, I think), on-set and on-dispose which are run when the reaction is set and unset from the DOM repectively. I'm not sure what derefed is. I'm pretty sure someone else can easily fill this in though.

PS I'm not sure if you knew this. If you did, we could possibly work together to create the docstrings you that are missing - there are many more than just these ones you highlight.

[metasoarous]

Wow... is this still outstanding? I've found the re-frame documentation is generally great for more in depth Reagent functionality, but it still surprises me that Reagent doesn't have more documentation about all of it's wonderful goodies. I'm generally pretty informed about ratoms and reactions, but I'd really like to know more about make-reaction in particular. I haven't seen anything about it on the re-frame documentation.

[piotr-yuxuan]

Hello :-)

Just a reminder about this. I come from re-frame documentation and I stumble upon argument on-dispose. There are no docs anywhere about these three on-set, auto-run and on-dispose and it may be good to have guideline on how to use it (or perhaps it's fine to remove them from the public API).

Names can be misleading: for instance, a previous comment on this issue states

the options hash can contain an auto-run boolean

but without documentation, I could also rely on Clojure naming convention to say it's not a boolean (would be auto-run?) but a function which run each time the reaction is called / changed.

[vemv]

Could the notion of a reaction itself be described more clearly?

Current explanation http://reagent-project.github.io/docs/master/ManagingState.html (Reactions are like cursors called with a function.) doesn't seem to shed much light.

Thanks - Victor

[simongray]

I came to this issue from a page of 2020 Google search results and I just have to note that this is still undocumented ;-)

[huima]

2021 and checking in to say the same :-D

Perhaps this issue could be linked as a docstring to the macro or link to the improved documentation in the github?