--- a/dwtx/jface/viewers/ITreeSelection.d	Mon May 19 13:41:06 2008 +0200
+++ b/dwtx/jface/viewers/ITreeSelection.d	Thu May 22 01:36:46 2008 +0200
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2005, 2006 IBM Corporation and others.
+ * Copyright (c) 2005, 2007 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
@@ -19,6 +19,25 @@
 
 /**
  * A selection containing tree paths.
+ * <p>
+ * It is recommended that clients do not implement this interface but instead
+ * use the standard implementation of this interface, {@link TreeSelection}.
+ * <code>TreeSelection</code> adds API for getting the {@link IElementComparer}
+ * of a selection (if available). This is important for clients who want to
+ * create a slightly modified tree selection based on an existing tree selection.
+ * The recommended coding pattern in this case is as follows:
+ * <pre>
+ * ITreeSelection selection = (ITreeSelection)treeViewer.getSelection();
+ * TreePath[] paths = selection.getPaths();
+ * IElementComparer comparer = null;
+ * if (selection instanceof TreeSelection) {
+ *   comparer = ((TreeSelection)selection).getElementComparer();
+ * }
+ * TreePath[] modifiedPaths = ... // modify as required
+ * TreeSelection modifiedSelection = new TreeSelection(modifiedPaths, comparer);
+ * </pre>
+ * See bugs 135818 and 133375 for details.
+ * </p>
  *
  * @since 3.2
  *