Documentation doesn't define fundamental concepts

[vspinu]

One "feature" of the existing documentation is that it doesn't pay much attention to defining basic concepts.

A couple of examples.

1. What is component in reagent context? Is it a function or the returned hiccup data structure or something else?
2. What is mounted component and how it differs from component?
3. In terms of the syntax, what is the difference between (fn [] [:div (some-component)]), (fn [] [:div [some-component]), (fn [] [:div some-component]), or just [:div [some-component)]? There is only a quick note concerning the first two: "The only difference would have been performance, since ”real” Reagent components are only re-rendered when their data have changed".
4. What is "real" component?
5. How do you define component's data?
6. How components are re-generated is only tangentially explained. There are two references on this but both are, at best, incomplete definitions:
   • "Any component that uses an atom is automagically re-rendered when its value changes".
     1. Does this mean that if I use one atom per application then all components will be re-rendered even on a small change of the atom's hashmap? So, I should use multiple attoms whenever possible?
     2. Does uses an atom mean that "the function that generates hiccup data structure derefs an attom"? I infer from the examples that the answer is "yes". That is, whenever value of an atom changes, all functions that deref that atom within their body will be called again to re-generate the hiccup data structures.
   • "The change could come from a deref’ed atom, the arguments passed to the component or component state".
     1. I guess arguments are the values passed to functions which produce hiccup structures. deref'ed atom is as in the above uses an atom idiom. But what is component state?

It could be that the docs assume knowledge of react and maybe all the above have unique implicit definition. Sorry if that's the case; my knowledge of react is close to zero.

I would expect, for a knowledgeable person, it would cost a tiny amount of time to create a small wiki glossary with exact definitions of the above concepts. I think It would dramatically improve the accessibility of the package for newbies like me. Thank you very much.

[vspinu]

Have just discovered that re-frame's main page and wikis clarify most of the above questions in a most fluent and informative way possible.

[mars0i]

reagent-cookbook also does a pretty good job of introducing basic concepts.

[gadfly361]

I think the recent docs that were moved from re-frame and #343 are sufficient to close this.