Name: rmT116609 Date: 05/29/2003


A DESCRIPTION OF THE PROBLEM :
1. The method documentation for javax.swing.PopupFactory.getPopup(...) is
   a bit ambiguous and unclear:

      ...getPopup(Component owner,
                  Component contents,
      ...
      Creates a Popup for the Component owner containing the Component contents.

   That sentence can seem to parse as:

      a Popup for <Component "owner" containing the Component "contents">
   
   instead of
 
      a Popup < <for Component "owner"> [and] <containing the Component
     "contents"> >
   

2. The second sentence seems scrambled, or at least virtually unparsable:

      owner is used to determine which Window the new Popup will parent the
      Component the Popup creates to.

  Which thing does what to which others?


3. This sentence also suffers from informal preposition use:

      x and y specify the preferred initial location to place the Popup at.


EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
1. One way to reduce ambiguity and (slightly) increase clarity:

       Creates a Popup for the Component owner _and_ containing the Component
       contents.

2. Who knows, giving the current wording. The preposition is too far from
    its verb to identify which verb it goes with. Don't put the preposition
    at the end of the sentence when that's too far away. (Change it to a
    "to which" at the right place, and then fix whatever else is wrong.)


3. Again, following the formal rule about keeping prepositions with their
    verbs keeps things clearer:

      x and y specify the preferred initial location _at_which_ to place the
      Popup.

ACTUAL -
Above.

URL OF FAULTY DOCUMENTATION :
http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/PopupFactory.html#getPopup(java.awt.Component, java.awt.Component, int, int)
(Review ID: 186642)
======================================================================