Add clarifying documentation to Io.links

[ElectreAAS]

If you're thinking of a symlink as an arrow A -> B, the signature val link: src:Path.t -> dst:Path.t -> unit might lead you to believe you should use it like so link ~src:A ~dst:B, but you'd be wrong!
It's the reverse you should be doing.
It threw me off for a loop, so I'm trying to improve the documentation.
Suggestions welcome

[Sudha247]

Good catch!

[ElectreAAS]

I pushed a new version with revised wording

[Alizter]

I think saying that the labels can be misleading is a bit strong, because then otherwise why did we choose them?

I think an explanation like the following is enough:

      [portable_symlink ~src ~dst] creates [dst] as a symbolic link 
      (or copy on Windows) pointing to [src]. *)

[ElectreAAS]

I think this is the convention held up by GNU ln and other tools, but that doesn't mean they're not weird

[Leonidas-from-XIV]

As an additional data point, I've heard this complaint a few times but ln is positional, in ln <from> <to> order which matches cp and nobody complains that cp is confusing.

[ElectreAAS]

I agree that cp isn't confusing, it works like you'd expect. What I didn't expect was for ln to work like a copy, where I'd figured it would work like an arrow.

I've pushed revised wording

[ElectreAAS]

Pushed revised wording, and rebased on main for good measure