Name: rmT116609 Date: 01/28/2003


DESCRIPTION OF THE PROBLEM :
The Javadoc-generated page for java.awt.Toolkit doesn't explain desktop
properties and regular properties sufficiently.

The method description for getProperty says only:

    Gets a property with the specified key and default. This method returns
    defaultValue if the property is not found.

Nothing in the page says:
- what type of properties they are (since they're apparently not the same thing
    as desktop properties)
- how to find out which properties exist (their names)
- where they come from (since there's no set method)
- what distinguishes them from desktop properties

The method description for getDesktopProperty says a little more:

Obtains a value for the specified desktop property. A desktop property is a
uniquely named value for a resource that is Toolkit global in nature. Usually it also is an abstract representation for an underlying platform dependent desktop setting.

That doesn't make completely clear what the difference between desktop and
regular properties is.

(There's only one Toolkit subclass instance, right? If so, then wouldn't regular properties associated with that single instance be Toolkit-global just like desktop properties? Or does that really mean "toolkit-global" (that
is, global to the underlying toolkit as opposed to the Java Toolkit subclass
instance)?)

Are they properties of the Java Toolkit subclass? (The phrase "[u]sually...
underlying" seems to suggest that.)

(Hey, on X11, are they whatever X11 objects (window properties? atoms?)
Netscape's "remote control" uses? (http://wp.netscape.com/newsref/std/x-remote.htmlhttp://wp.netscape.com/newsref/std/x-remote.html)

That also doesn't say how to find out what desktop properties there are.
(If they're platform-dependent, Toolkit's Javadoc could refer to some
release-specific (or common all-inclusive) file that says how to find the
properties for the platform (on X11: if they are standard X11 properties, refer
the reader to the appropriate X11 documentation; if they are properties of
whatever window manager is running, state that to the reader).
(Review ID: 166221)
======================================================================