Better documentation

[texttechne]

We should put some effort into making the documentation better:

• Rewrite the introduction: Purpose of JSX, that it is not a dedicated template language and why control statements are a perfect fit to extend the language
• Add a introductory section which explains pro and cons of JSX-Control-Statements, especially in comparison to other libraries which try to implement conditionals (see Can this be done with vanilla React? #36)
• Cleaner API documentation for control statements. Use a table layout.
• Add a section for alternative, pure JS approaches for conditionals

[AlexGilleran]

Sounds good to me. It is a bit hard to figure out exactly what order these should all go in though - if the readme takes too long to get to an example will people be less likely to bother reading through and eventually using it? Cleaner API docs is definitely a good idea.

[texttechne]

@AlexGilleran Done. Could you review?

[AlexGilleran]

@texttechne That's really great. I just had a few tweaks (capital letters, removing the notice about JSTransform at the top, changing some wording around, adding a link to react-if and reactjs/react-future#35). Tell me what you think :)

[texttechne]

The link to the react-future discussion is a really useful addition 👍
Removing the notice about JSTransform also makes sense at this point.

Regarding the link to react-if, I've thought about that, but didn't want to mention this or any of those libraries directly. Could be interpreted as blaming or finger pointing... but I leave this up to you 😉

And for completeness' sake there is the lazy evaluation workaround by wrapping the body in a function, although it is not explicitly mentioned in the docs. It's hinted at:

            <If condition={ this.props.age >= this.props.drinkingAge }>
                <Then><span class="ok">Have a beer, {this.props.name}!</span></Then>
                <Else>{() =>
                  <span>Sorry, {this.props.name}, you are not old enough.</span>
                }</Else>
            </If>

See the else branch; of course, this function wrapping would be required for the if branch as well. After having written it down, it is probably not worth to mention, after all it is still an ugly workaround which defeats the purpose of any such library.

Thanks for the additions, corrections and stuff!
Would you mind to make a release soon, so we get this also published on npm?

[AlexGilleran]

Haha I never actually thought of the react-if thing that way, I thought of it more as a nod to what inspired this whole thing.

Yeah I agree with leaving that out. Will release shortly :) 👍