Open CGamesPlay opened 7 years ago
I thought about adding this nuance to the documentation, but I think that it actually detriments from the explanatory power of the documentation by adding extra complexity. Anyone who really wants to rely on beforeState
is probably doing something beyond the scope of this module anyways.
Do you have a better suggested wording, or do you think your comment is worth preventing merging this for?
my big concern is that how it works should be irrelevant. the readme should show how to use it, but the internals should be a black box where folks don't need to understand it. if they'd like to understand it, it's < 200 LOCs. I think it's perfectly fair to ask folks to read the code if they'd like to fully understand it. Then I don't have 2 sources of truth (1 in english, 1 in javascript)
I'm inclined to agree with you, although I will point out that you reference beforeState
and history
in the very next section ("this will transform your state..."), so revisiting that section of the documentation to hide more of the implementation details may be worthwhile at some point in the future.
Still, I removed the implementation details from my patch and shortened the explanation to stick to "how to use redux-optimistic-ui".
This was pretty confusing for me as a first-time user and I had to read the source code and do several experiments to figure this out. I'm submitting this change to the README that adds a section on the specific behavior of
BEGIN
,COMMIT
, andREVERT
and also includes a recommendation on how to use them effectively.I also cleaned up the formatting. FYI GIthub doesn't recognize headings unless there's a space following the
###