Creating Clearer Method Names & Concepts

[Mark Fortner]

I still find myself tripping over the names of methods or concepts in the
JavaFX API -- where the API says "X", but only after you dig into the
documentation do you discover that it really means Y.

For example, property "Invalidation" doesn't really communicate what the
code is actually doing.  The property isn't invalid, it's value has never
been validated (we don't yet have that concept in the API), so how can the
property be "invalid"? All that's really indicated is that the property
value has been changed -- although the subtle distinction between
InvalidationListener and ChangeListener is lost on me and I always use a
ChangeListener.

At some point when we have a validation framework for JavaFX, how will the
concomitant method calls that come with that framework, play out with the
existing method calls. There will probably be a lot of head scratching
going on.

And there's the documentation for *Axis.toNumericValue*, and *
Axis.toRealValue*:

http://docs.oracle.com/javafx/2/api/javafx/scene/chart/Axis.html#toNumericValue(T)

http://docs.oracle.com/javafx/2/api/javafx/scene/chart/Axis.html#toRealValue(double)

Granted, "All axis values must be representable by some numeric value." But
what I really want to know is are we translating from user space
coordinates to data space coordinates? Or vice-versa?  What is a "real
value" and what is a "numeric value"? Aren't all values in an XY chart
numbers?

And why is that if I'm translating from user space to data space that I
still need to take into account the width of the Y-Axis?  Shouldn't I be
able to get coordinates relative to the chart's content space?


Cheers,

Mark