Allow reference to polymorphic variants when possible

[panglesd]

A break from the 3.0 design!

Fixes #907 by allowing references to polymorphic variants when the type is given in the reference and the type's manifest is a polymorphic variant.

The ` in the constructor name is allowed and not mandatory.

References without specifying the parent type were not requested in #907 and could be added in another PR.

The last commits illustrate a problem: the polymorphic variants do not have an ID, so the resolved references for polymorphic variants are turned into a normal constructor identifier. This is not ideal.
If needed, the model could be modified to represent for "types whose manifest is a single polymorphic variant" in a way that allows to define ids to the polymorphic variants.
That is a bigger refactoring, but I can do it if you think that is needed.

type switch = [ `On | `Off ]

(**

   References with type as parent work:
   - {!type-switch.On}
   - {!type-switch.`Off}
   - {!type-switch.constructor-On}
   - {!type-switch.constructor-`Off}
   - {!switch.On}
   - {!switch.`Off}
   - {!switch.constructor-On}
   - {!switch.constructor-`Off}

   References in the environment don't work:
   - {!On}
   - {!`On}
   - {!constructor-On}
   - {!constructor-`On}

*)

[jonludlam]

I don't understand.

[panglesd]

Polymorphic constructors do not have an ID. When turning a resolved polymorphic constructor reference to an ID, a normal constructor ID is used.
But then, we need to ensure that this id, when turned to an href with anchor, does correspond link to the right place (that is, the page exists (which is always the case but also the html anchor exists).
Anchors are generated in Url.Anchor.polymorphic_variant, more precisely here. This function just tries to "force" the target anchor in IDs for constructor and the anchor for polymorphic constructor to correspond. I can remove it and replace it by a more detailed comment.

I can also add IDs to polymorphic constructors that can be referenced, that means changes to Lang but maybe it is worth it.

[jonludlam]

FYI I'm working in this area right now (looking at Names & associated issues), so I'll have a more concrete view on this when I'm done :-)

[EmileTrotignon]

@jonludlam Are you done with looking at names and associated issues ?

[jonludlam]

Yes, I'll take a look tomorrow.

[jonludlam]

OK, this all looks sensible to me. We're not currently attempting to do any resolution of constructors that aren't explicitly in the type definition, e.g.:

type switch = [ `On | `Off ]
type switch2 = [ switch | `Partial ]

(** This doesn't resolve: {!switch2.On} *)

so there's some scope for improvement if we want to go further.