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

Javadoc for event firing methods in DefaultTreeModel is incorrect

    Details

      Description

      URL OF DOCUMENTATION :
      http://java.sun.com/javase/6/docs/api/javax/swing/tree/DefaultTreeModel.html

      A DESCRIPTION OF THE PROBLEM :
      In DefaultTreeModel class, the event firing methods have incorrect documentation for "source" and "path" parameters. The refering methods includes:

      fireTreeNodesChanged
      fireTreeNodesInserted
      fireTreeNodesRemoved
      fireTreeStructureChanged

      All javadoc for parameters "source" and in these methods document "source" parameter as the changed node. In fact, the source parameter is the object responsible for generating the event to be fired.

      If you look in the source code for DefaultTreeModel, you will see that
      in these methods, the source parameter is passed into TreeModelEvent's
      constructor, also as source parameter. And from TreeModelEvent
      documentation, it describes source as:

      the Object responsible for generating the event (typically the creator
      of the event object passes |this| for its value)

      Moreover, if you look at usages of these methods inside DefaultTreeModel
      itself, you will see that they are all pass "this" as source parameter,
      in this case, "this" is the DefaultTreeModel instance, which is the
      object responsible for generating the event, not the node changed,
      inserted or removed.

      Point to note, this source parameter is the same as source attribute in
      EventObject class.

      In fact, the parameter that describes node changed, inserted or removed
      is combination of path, childIndices and children parameters. You can
      see from the source code in DefaultTreeModel that these event firing
      methods is just pass on these parameters to TreeModelEvent constructor.
      Therefore, the intent and documentation for these parameters should
      resemble TreeModelEvent's.

      EXPECTED BEHAVIOR :
      To give a concrete example, let's take a look at fireTreeNodeChanged()
      documentation. The desired documentation should be identical to TreeModelEvent's.

      source - the Object responsible for generating the event (typically the
               creator of the event object passes 'this' for its value).
        path - an array of Object identifying the path to the root of the
               modified subtree, where the first element of the array is the object
               stored at the root node and the last element is the object stored at
               the changed node.

      ACTUAL BEHAVIOR :

      fireTreeNodeChanged() documentation:

          |source| - the node being changed
          |path| - the path to the root node
          ...

      And this is documentation for TreeModelEvent

          |source| - the Object responsible for generating the event
          (typically the creator of the event object passes |this| for its value)
          |path| - an array of Object identifying the path to the parent of
          the modified item(s), where the first element of the array is the
          Object stored at the root node and the last element is the Object
          stored at the parent node
          ...

      You can see that the documentation for fireTreeNodeChanged is incorrect.
      path parameter is not path to the root node. It is actually path to the
      parent of the modified item(s).

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                svioletsunw Scott Violet (Inactive)
                Reporter:
                jleesunw Jon Lee (Inactive)
              • Votes:
                0 Vote for this issue
                Watchers:
                0 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved:
                  Imported:
                  Indexed: