Improve the documentation of Suffixed/LiftFrom/LiftInto

[ExpHP]

Logging an issue from discussion on #89.

The documentation of Suffix is entirely inadequate:

An index denoting that Suffix is just that.

At bare minimum it needs to link to LiftFrom/LiftInto, since otherwise the average person just happening upon it from e.g. the module page (a.k.a. me from two days ago) has absolutely no idea what they're even looking at.

LiftInto shows examples of larger hlists being created from smaller ones, but it's not clear from those examples what the rules and limitations are. LiftFrom doesn't even have examples like that.

[Centril]

Agree with this!

If you have some time to try out improvements to LiftFrom wrt. using permutations of subsequences that would be super cool =)

[ExpHP]

If you have some time to try out improvements to LiftFrom wrt. using permutations of subsequences that would be super cool =)

P.S. my gut feelings on this are that, in the world of type inference, "more general" != better, and that support for arbitrary permutations would not necessarily be better, but just different. For instance, all of the existing examples of LiftFrom would stop compiling because they have multiple () elements.

What really needs to be known is what use case we are optimizing for. And it's hard for me to answer that question since, personally, I can't really think of a use case for LiftFrom in any of my own code.

---

(that said, I certainly wouldn't mind exploring the question of "is it even possible?" :wink:)