Initial stab at documenting the kind system

[ccasin]

As title.

This is a draft PR because at a minimum there are some bits left to be filled in. But, also, I think we need some discussion about how various bits of the system should be presented. Here, I've tried to present things uniformly as they really are (or will be in a few weeks), so that a whole bunch of special cases aren't needed. But in practice our system obscures this reality a bit (for example, around nullability), and I'm not sure how best to handle that.

I've tried to write this more as useful documentation than as a complete reference.

[goldfirere]

I think this is fantastic.

[goldfirere]

It actually has 3 possible values: external_ < external64 < internal, so that immediate64 can be mod external64.

[ccasin]

🤦‍♂️

I added a note about external64 and jsoo/wasm - you may want to check its accuracy.

[goldfirere]

Not in great detail. But I do think there should be some commentary mentioning at least these highlights:

• The default kind for type t is value
• The kind for an extensible type is value
• The kind for a boxed variant with no fields is immediate
• The kind for a boxed record or variant with no mutable fields (but at least one field) is immutable_data with <<all the fields>>
• The kind for a boxed record or variant with at least one mutable field is mutable_data with <<all the fields>>
• The kind for an unboxed record is <<product of the fields' layouts>> mod <<everything>> with <<all the fields>>
• The kind for an [@@unboxed] record or variant is <<layout of the payload>> mod <<everything>> with <<the field>> (by further special decree, this with does take nullability into account!)
• The kind for an unboxed tuple is <<layout of the components>> mod <<everything>> with <<the components>>
• The kind for a closed polymorphic variant with no fields is immediate
• The kind of a function is value mod aliased contended
• The kind for other types is value
• Kinds for other types may improve over time. For example, we expect to change the kind of a boxed tuple to be immutable_data with <<the components>>. Similarly, we expect to improve on the kinds of polymorphic variants and first-class modules.
• The kind of a private abbreviation is the kind of its right-hand side. We expect to allow users to give a private abbreviation a superkind of its right-hand side (thus improving abstraction) soon.

A full specification of how with-bounds interact with subsumption is probably beyond the scope of this document. I can produce some hand-wavy text about how we try our best here if you like.

[ccasin]

OK, I've integrated most of the feedback here - thanks for catching all those typos. A couple notes:

Nullability: I've reworked the doc to just not mention nullability at all until the section on it. Despite my earlier whinging, I think this works out fine, and everything remains accurate, likely due to the good design choice to have things as they are. @dkalinichenko-js may want to check the nullability section for accuracy.

With-kinds: This is the remaining thing. I've realized I have no idea what the current syntax is. I propose we ask someone familiar with the current implementation (@glittershark , maybe?) to fill in that part of this doc. (You can just push to this branch)

[glittershark]

With-kinds: This is the remaining thing. I've realized I have no idea what the current syntax is. I propose we ask someone familiar with the current implementation (@glittershark , maybe?) to fill in that part of this doc. (You can just push to this branch)

I'll gladly do this, ideally sometime next week (or if you want it sooner, @liam923 or @goldfirere might have time before then?)

[liam923]

I'll gladly do this, ideally sometime next week (or if you want it sooner, @liam923 or @goldfirere might have time before then?)

I don't think I'd be able to get around to it before next week.