Add Docs for First Class Modules

[ryyppy]

First Class Modules were not documented in Reason so far, mostly on purpose to not overwhelm early adopters of the language, and due to fear that ppl will go crazy with abstractions when learning these concepts.

Let's propose to create a document in the Reason Manual within an "Advanced" section, explaining the concepts of FCM (also the acronym):

• How do you write / use FCMs
• When are they useful?
• When NOT to use them / offer alternative patterns
• Hint on performance / readability / generated output implications in JS (only use them when really needed, good hints on API building practise)

Examples should be less abstract, no single letter placeholders, no Mathematical patterns, in best cases UI related.

Related to #145

[mlms13]

I don't know of significant performance/generated-readability issues (other than what's already present in Functors, which are already documented on the Module page).

For context, here's a code sample I put together to look into the generated JS.

Basically, in the example, you can call Array.containsBy(eqFn, value, array) or you can call Array.contains((module SomeModule), value, array);. The JS output in the second case just passes in {eq: SomeModule.eq} instead of passing in a plain function.

This probably isn't a great example for demonstrating why you'd want this (and the obvious alternative in this case is "pass in exactly what you need to the function instead of packaging things up in a module"), but it highlights that the output JS for packing and unpacking modules isn't any worse than using a record to pass a collection of values/functions.

[austindd]

@mlms13 Yeah, if I recall correctly, there was some kind of documentation (or perhaps someone's blog post) about why Belt insists on using FCM's for Set & Map. But it's not immediately obvious to newcomers.

[austindd]

I would, however, say it takes more thought to pack/unpack a module in many cases. There is a particular set of conventions people use which tends to work well, e.g. specifying very limited module signatures in the function argument, so many different modules will work with minimal conversion overhead (like renaming functions).

There are a lot of things that we now take for granted, which ultimately boil down to informal conventions.

Another good example is the "type t" pattern for modules oriented around a specific data type. This integrates nicely with most functor designs, which is, in turn, a product of community convention.

These are things that most people end up discovering eventually through trial and error. I suppose they could be called "design patterns." These are arguably just as important to document, IMO.