[BuckleScript] Proposal for new common-data-types section

[ryyppy]

Introduction

Right now, the bucklescript documentation provides a common datatypes section to describe so called shared and non-shared data types.

• Shared data types are Reason types that have an equivalent JS data type (like int, string, or float)
• Non-shared data types are Reason specific data structures with a different JS representation (e.g. module, variants, lazy values)

Additionally to this separation, some Non-shared data types have a runtime representation that is internal and should not be relied on (lazy values, variants etc.), but this will change in the future, where more and more data structures will be exposed as a public representation as well.

The Problem

Wording

The terms shared / non-shared and data types are both problematic. Constructs such as modules and functors are no types, but we want describe a runtime representation for all constructs of the language.

shared also has multiple definitions (according to @cristianoc: Shared is very loaded with shared values, meaning aliasing), so it would be great to eliminate that ambiguity as well.

Keeping track of versions

Over time, runtime representations changed to the better or even got exposed as public representation people can rely on. Right now, we sparsely use any structure on how runtime representations differ between versions (for example we mention v7 for records-as-objects, but don't really talk about previous representations).

That might not be a problem right now, but it might be for the future when new changes are coming in, so it would be great to have an idea to represent changes in different versions.

Proposal

To give a clearer overview over the whole common-data-types topic, we propose following changes:

Better wording

• Rename data types to language constructs to be able to express types, but also constructs such as modules / functors etc
• Rename shared / non-shared to public / private

We'd then be able to express either one unified section, or two distinct sections for private / public representations without ambiguity:

Language Construct	JS Runtime representation	Public
int	float	yes
module	object	yes
record	object	yes
variant	object	yes
lazy value	object	no

we can also add interactivity with specific UI for toggling between public / private if necessary. This table could also act as a TOC to refer to the details of each language construct, where we can discuss the actual shape of the runtime representation and also add infos about the version.

Example:

## module

**since v9.3:**

```re
module Foo = {};
```

```js
let Foo = {};
```

**previously**:

```re
module Foo = {};
```

```js
let Foo = [];
```

We can think about collapsible elements as well to hide older version information in case the content gets too bulky.

Conclusion

With the proposed changes, we could clean up ambiguous terminology and make it easier to explain what language constructs Reason users can rely on when interoping with JS.