A DESCRIPTION OF THE PROBLEM :
More than 5 years ago, a bug (ID 4182206) was reported against the documentation of TitledBorder and BorderFactory.createTitledBorder(String). The problem was that both of these docs claim that the default border used by a TitledBorder is EtchedBorder, while the actual border used is dependent on a L&F property. This bug was closed as fixed back in 1998, and the TitledBorder documentation was indeed fixed, but the BorderFactory documentation was not. The method BorderFactory.createTitledBorder(String) still claims that the default border used is an EtchedBorder (the default in the Metal L&F is actually a LineBorder).

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
The documentation should reflect the fact that the default border is dependent on the Look and Feel, and is not always an EtchedBorder. As a helpful note, it could even recommend that the user explicitly pass a border when creating a TitledBorder if they want consistent results across L&Fs.
ACTUAL -
Creates a new title [sic] border ... using the default border (etched), using the default text position ...

URL OF FAULTY DOCUMENTATION :
http://java.sun.com/j2se/1.5.0/docs/api/javax/swing/BorderFactory.html#createTitledBorder(java.lang.String)
###@###.### 2005-04-26 06:16:15 GMT