A DESCRIPTION OF THE PROBLEM :
The documentation for JComponent states that if a subclass wishes to display a tool-tip that is dynamically determined according to where the mouse is located, then it should override the getToolTipText(MouseEvent) method.
However this alone is not sufficient. An instance of JComponent or subclass thereof will not display any tool-tip unless the setToolTipText(String) method has been invoked with a non-null argument.
The documentation is misleading as it fails to explicitly state that JComponent will not display any tool-tip unless the setToolTipText(String) method is invoked. This information can only be found within the Java Tutorial.


EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
The JComponent documentation should fully explain the tool tip behaviour. Specifically, the comment for getToolTipText(MouseEvent) method should explicilty state that for a subclass to override this method in isolation will not automatically cause the subclass to begin displaying tool-tips.
The interaction between the getToolTipText(MouseEvent) method and setToolTipText(String) method should be explained.
ACTUAL -
"If a component provides more extensive API to support differing tooltips at different locations, this method should be overridden."
[This statement is made with no qualification; so it erroneously implies that overriding the method, in isolation, is sufficient to achieve the effect].


URL OF FAULTY DOCUMENTATION :
http://java.sun.com/j2se/1.5.0/docs/api/javax/swing/JComponent.html