Index: /trunk/src/org/openstreetmap/josm/data/osm/DataSelectionListener.java
===================================================================
--- /trunk/src/org/openstreetmap/josm/data/osm/DataSelectionListener.java	(revision 12096)
+++ /trunk/src/org/openstreetmap/josm/data/osm/DataSelectionListener.java	(revision 12097)
@@ -21,7 +21,10 @@
     /**
      * Called whenever the selection is changed.
-     * @param e The selection change event.
-     */
-    void selectionChanged(SelectionChangeEvent e);
+     *
+     * You get notified about the new selection, the elements that were added and removed and the layer that triggered the event.
+     * @param event The selection change event.
+     * @see SelectionChangeEvent
+     */
+    void selectionChanged(SelectionChangeEvent event);
 
     /**
@@ -53,5 +56,5 @@
          * <p>
          * This collection cannot be modified and will not change.
-         * @return The primitives
+         * @return The primitives that were removed
          */
         Set<OsmPrimitive> getRemoved();
@@ -63,5 +66,5 @@
          * <p>
          * This collection cannot be modified and will not change.
-         * @return The primitives
+         * @return The primitives that were added
          */
         Set<OsmPrimitive> getAdded();
@@ -76,5 +79,5 @@
          * Test if this event did not change anything.
          * <p>
-         * Should return true for all events that are fired.
+         * This will return <code>false</code> for all events that are sent to listeners, so you don't need to test it.
          * @return <code>true</code> if this did not change the selection.
          */