Currently, public API for JComboBox and it's UI delegates contains javadoc which describe the details of it's implementation. Refactoring and bug fixing over the course of it's history has made this javadoc out of date.
The javadoc should be checked and revised so that it describes the behaviour of the method rather than the implementation details. Also, some of the javadoc for "protected" methods and fields which should really have been private should be removed so that overriding or calling these methods are not encouraged.
Rewriting the javadoc will focus on the following classes:
- JComboBox
- BasicComboBoxUI
- BasicComboPopup
For example, the javadoc for the method JComboBox.addItemListener() explains that "An event is not sent in response to calls to setSelectedIndex or setSelectedItem". This is false.