United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
Bug ID: JDK-4394300 RFE: Javadoc for JComboBox and UI delegates should not document implementation
JDK-4394300 : RFE: Javadoc for JComboBox and UI delegates should not document implementation

Details
Type:
Enhancement
Submit Date:
2000-12-01
Status:
Resolved
Updated Date:
2001-01-17
Project Name:
JDK
Resolved Date:
2001-01-17
Component:
client-libs
OS:
windows_nt
Sub-Component:
javax.swing
CPU:
x86
Priority:
P3
Resolution:
Fixed
Affected Versions:
1.4.0
Fixed Versions:
1.4.0 (beta)

Related Reports

Sub Tasks

Description
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.

                                    

Comments
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
                                     
2000-12-04
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
merlin-beta

FIXED IN:
merlin-beta

INTEGRATED IN:
merlin-beta


                                     
2004-06-14



Hardware and Software, Engineered to Work Together