Remove rest_length field from DistanceJoint.

[shanecelis]

Objective

Remove rest_length from DistanceJoint which is ignored if length_limits is present.

Problem

I was using distance joints as muscles, changing their rest length to exert them. However, when I set the length_limits, nothing worked anymore. I looked into the code and saw my error: rest_length is ignored when length_limits is set, which seems like a foot gun to me. A TODO in the code said "Remove rest_length" and after surveying the code, I agreed.

Solution

I removed rest_length and with_rest_length() from DistanceJoint.

I changed the name and arguments of with_limits() to with_length_limits(). I think this makes it clearer that it's associated with the length_limits field. And I altered the arguments to accept Into<DistanceLimit>, so that it can be set with a Scalar, a pair of Scalars, or a DistanceLimit. My hope was that with_length_limits() could serve in place of both with_limits() and with_rest_length().

Edit by Jondolf: The changes to with_limits were reverted for now, see this message.

Auxillary Changes

Some doc tests weren't passing. I added the necessary ampersands (&) to make them pass.

---

Changelog

• Added: From<Scalar> and From<[Scalar; 2]> for DistanceLimit and AngleLimit.
• Added: From<Scalar> and From<(Scalar, Scalar)> for DistanceLimit and AngleLimit.
• Changed: Removed rest_length field from DistanceJoint.
• Changed: Removed with_rest_length() method from DistanceJoint.

Migration Guide

• Replace DistanceJoint::with_rest_length(1.0) with DistanceJoint::with_limits(1.0, 1.0).
• Replace joint.rest_length = 1.0 with joint.length_limits = 1.0.into().

[Jondolf]

Thanks! And sorry for getting to this so late 😅

I pushed some changes:

• Also implement From<[Scalar; 2]> for DistanceLimit
• Implement the same conversions for AngleLimit
• Revert the API changes related to with_limits; it takes min and max separately again

That last change might be the most contentious. My motivation there is:

• I would like the limit APIs to be consistent. Having DistanceJoint::with_length_limits take impl Into<DistanceLimit> is inconsistent with e.g. the PrismaticJoint or RevoluteJoint APIs.
• The conversion behavior is not entirely clear without reading through the docs or source code. Creating a distance limit from a scalar value can easily be interpreted as limiting the maximum distance, not both the minimum and maximum distance.
• Typing out the min and max with the same value is really not much longer, and it is more explicit and readable.
• Not using impl Into allows the method to be const.

In a follow-up, we could consider adding with_min_distance and with_max_distance helpers for the cases where you only want to specify one though.

Note that #803 also includes similar changes, but I'll merge this one first to do things more incrementally :)