I noticed that the JavaDocs in general give very little pause about how objects are being referenced after say calls to bind, bindBidirectional, addListener... and now also Timelines. This makes it difficult to foresee whether or not certain actions will cause memory leaks because of pieces of UI never going out of scope.

A trivial example I recently discovered (without any hint in the docs) is that if you create a Timeline, even one with a limited duration, it will be referenced by some global animation handler internal to JavaFX. If your Timeline is created as an anonymous inner class, this means the Pane it is constructed for will also be referenced, and thus the Pane never goes out of scope. Even if it is not an anonymous inner class, the Timeline itself can cause memory leaks as well -- apparently it is crucial stop is called to get it gc'd, but this is not mentioned at all.

I noticed that using Jira one can uncover similar problems that were fixed in some of the Samples, and the fix was to call stop() when appropriate. This should be clear from the docs.

Other things that are not clear from the docs is what happens after a Timeline finishes -- does calling playFromStart() finally result in the stop or paused state? Does the Timeline stop at all after 10 seconds if the highest known KeyFrame is 10 seconds, or does it keep running?

I could find out all of these things by experimenting, but I shouldn't have to rely on undocumented behaviour.