Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-4871558

PopupFactory.getPopup(...) wording ambiguous/unclear, and scrambled

    XMLWordPrintable

    Details

      Description

      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)
      ======================================================================

        Attachments

          Activity

            People

            Assignee:
            Unassigned Unassigned
            Reporter:
            rmandalasunw Ranjith Mandala (Inactive)
            Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

              Dates

              Created:
              Updated:
              Imported:
              Indexed: