search

RobotLocomotion / drake

Model-based design and verification for robotics.
https://drake.mit.edu
Other
3.19k stars 1.24k forks source link

Makes multibody/constraint private within examples/rod2d #21445

Closed amcastro-tri closed 1 month ago

amcastro-tri commented 1 month ago

Resolves #21156.

We move the entire multibody/constraint into the only place it gets used examples/rod2d. The docs are removed from our public Doxygen modules to avoid this old confusion users have that we have an LCP solver in Drake. The docs are now a local README file in examples/rod2d/constraint.

This change is Reviewable

jwnimmer-tri commented 1 month ago

In #21156, we proposed removing the code. Demoting the documentation off of the website is a good start, but if we're going to remove the code anyway we might as well just remove the docs outright? Or if we're going go keep the code, the docs should stay on the website (but move to a different section, or be part of the class overview).

Could you reply (here or in that issue) about what the plan is for this code?

If you'd like to refer to the docs later, forevermore they will appear here. The catch-phrase we use is "git remembers". The only things on master should be things currently useful. If we don't use it, we should delete it and use git to read the old copies of it.

jwnimmer-tri commented 1 month ago

I think it does have a nice pedagogical value ...

Could you elaborate on this? I think this is where we differ. I might be missing something, though.

For my money, if we don't think this algorithm is useful in practice for robotics, then neither the algorithm nor its example should survive on master, and we should retire it into "git remembers".

jwnimmer-tri commented 1 month ago

If the example is really crucial and the only sticking point, then another solution is to move the contact_solver code into the examples/rod2d directory. Since we think it's undesirable for robotics users to call it, having it be part of the installed packages is also undesirable. Moving it to examples allows the demo to still run, but undoes the problem where it looks like something users should try to use.

jwnimmer-tri commented 1 month ago

Once @SeanCurtis-TRI is happy with the new version (you two can iterate as needed), then I'll circle back here and add the deprecation shims so that this isn't a breaking change.