Any feedback on this documentation of sub-typing would be appreciated!
-
“Subtyping” should be spelled without a hyphen.
-
The section on actor subtyping claims that " Actor
V2
is technically NOT a subtype of actorV1
(like in the case of object subtyping)". That’s incorrect. In Motoko, subtyping on actors follows exactly the same rules as on objects. -
In the section on function subtyping there is a note saying: “There is an exception for variant return types in new versions of Candid”. This note (which is repeated twice) is misleading in several ways. Candid has more permissive subtyping rules on variants than Motoko does, but they apply everywhere; there is no exception specific to function types. It also has similarly more relaxed rules for object types. (Also, technically, these more liberal rules always existed in Candid, but for variants they were broken for a while due to other changes.)
Specifically, in Candid, object supertypes can have more fields as well, as long as those are optional. Dually, variant supertypes can have fewer fields as well, as long as the whole variant is optional. That greatly extends the set of changes that are legal and safe for upgrades. Since Candid is what matters fur upgradability, maybe this section needs to distinguish between Motoko and Candid, and explain the difference. Subtyping in Motoko has a different role (mainly, supporting OO-style patterns), technically, it is neither necessary nor sufficient for upgradability.