API design and language cleanup.

[cristianoc]

Trying to consolidate some common themes emerging in received feedback, and to define the language to talk about them. The goal here is to have a cleanup pass on outstanding questions, API design, and documentation.

Terms

Type and Value.

Import and Export something.

Modules and Classes.

Renaming when e.g. type is a keyword, or A is capitalized, or using a different name for binding is useful.

Immutable Fields of objects and records are immutable by default, and arrays are opt-in immutable by using ImmutableArray.t.

Type Expansion see below.

Principles

1. If you’ve created some binding in one module, you should be able to use it from another module. (Instead of creating the same binding once again).
   Related: @ybybzj’s issue Generate opaque types corresponding to an existing Flow/TS type. #63.

2. It should be clear whether an annotation means that you’re importing or exporting something.
   Values can be either imported or exported, not both. Values already have a special syntax for export: the external keyword.
   Types can be imported, exported, but perhaps even both (e.g. import a JS type that is a string, and use it as a string in Reason, one needs to check that the two representations are consistent). The information on whether a type is imported or exported must be in the annotation.

3. If in doubt, the default meaning of an annotation is export. But, one could have also an explicit annotation. E.g. for types, export is the default, but one could add a @genType.export annotation too, to be super clear.

4. If an exported type is defined in terms of another type which is not annotated, what happens should be clear. Type expansion could be interesting to have, where types are expanded (i.e. inlined) until one reaches an annotated type, or a cycle. Also, should type expansion work across modules, and is that easy to implement? See also Support for tuples #71.

Problems and solutions

Q: How can I add annotations if I don't have, or can’t change, the code?

Example1: standard library, Belt, ReasonReact. (For now: shims).

Example2: @MarcelCutts on "exporting a type generated by GraphQL”. Or a type coming from invoking a functor.
Progress can be made on the second example by looking into Type Expansion.
Related: #64

Q: What about JS classes?

There’s not a clear answer for now.
Related: @ybybzj’s issue #63

Q: What should Modules export to, and with what representation, in the JS world?

There's an object-like quality in the values they contain, but a namespace-like quality in the types they contain.
Related: #42
Related: #41

[cristianoc]

This has been incorporated in the README and code structure.