JDK-4394300 : RFE: Javadoc for JComboBox and UI delegates should not document implementation
  • Type: Enhancement
  • Component: client-libs
  • Sub-Component: javax.swing
  • Affected Version: 1.4.0
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • OS: windows_nt
  • CPU: x86
  • Submitted: 2000-12-01
  • Updated: 2001-01-17
  • Resolved: 2001-01-17
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
1.4.0 betaFixed
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.

CONVERTED DATA BugTraq+ Release Management Values COMMIT TO FIX: merlin-beta FIXED IN: merlin-beta INTEGRATED IN: merlin-beta

EVALUATION The javadoc should be changed. Will have to work with JCK and Docs to write the correct javadoc. mark.davidson@Eng 2000-12-01 As part of this project, the semantics of selecting a ComboBox item should be clearly specified. There are some edge cases when programmatically selecting an item which is unclear. What should be the current combo box selection when: * Calling setSelectedItem() with an item that is not managed in the list? Currently, the combo box will select the first item in the list. * What should the editable state of the combo box have on the current selection? Currently, the DefaultComboBoxModel allows the selected item to be a non-null arbitrary item. This was meant to cache the edited item so that it could be retrieved and added to the combo box. The ambiguity of selecting an item in the combo box was addressed in bug 4163988. The javadoc was changed to reflect the implementation before we could assess that this is the correct semantics. mark.davidson@Eng 2000-12-04