[ODE] Updating ODE documentation (was: hello world)

[Adam Moravanszky]

A suggestion for doc improvement:

Methinks the documentation really needs to document the meanings of ODE
parameters better.  For example, there is a contact bounce parameter.  The
docs say that it has to be in [0,1], and describes the semantics of the two
extremes.  But it has nothing more, so Russ could be using some sort of
crazy nonlinear mapping in that range for all I know.  (I assume he doesn't
though. :-) )  I would actually include a definition, like:

The coefficient of restitution is the ratio of the differences in velocities
before and after the collision.

And include a formula too, since such a sentence can be confusing.  Then
document the variables in the formula.  Also, if the value has some sort of
unit -- unfortunately this coefficient doesn't -- then document that too.
Finally, I think the docs should refer to these numbers by their real names,
like "coefficient of restitution" in this case, instead of cute names like
'bounce'.  If someone hasn't read all about what "coefficient of
restitution" is in their high school physics book, they will probably not be
using ODE anyway.

(If surface.bounce is indeed only some weird fudge factor instead of what
I'm talking about, then forget what I said; then it is not only the docs
that need work...)

But again, bounce is only an example, I am actually curious about such a
description for friction, more on that in the next email.


--Adam