Fixed bug 420741: Decorator manager extension point and DeviceResourceDescriptor classes must mention resource life-cycleI20140107-0800

2 files changed, 13 insertions, 8 deletions

diff --git a/bundles/org.eclipse.jface/src/org/eclipse/jface/resource/DeviceResourceDescriptor.java b/bundles/org.eclipse.jface/src/org/eclipse/jface/resource/DeviceResourceDescriptor.java
index b7ce8c521b4..9b5b19f6528 100644
--- a/bundles/org.eclipse.jface/src/org/eclipse/jface/resource/DeviceResourceDescriptor.java
+++ b/bundles/org.eclipse.jface/src/org/eclipse/jface/resource/DeviceResourceDescriptor.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2004, 2006 IBM Corporation and others.
+ * Copyright (c) 2004, 2014 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
@@ -13,10 +13,14 @@ package org.eclipse.jface.resource;
 import org.eclipse.swt.graphics.Device;
 
 /**
- * Instances of this class can allocate and dispose SWT resources. Each
- * instance describes a particular resource (such as a Color, Font, or Image)
- * and can create and destroy that resource on demand. DeviceResourceDescriptors
- * are managed by a ResourceRegistry.
+ * Instances of this class can allocate and dispose SWT resources. Each instance describes a
+ * particular resource (such as a Color, Font, or Image) and can create and destroy that resource on
+ * demand. DeviceResourceDescriptors are managed by a ResourceRegistry.
+ * <p>
+ * <strong>Note:</strong> It is recommended that subclasses implement <code>#equals</code> and
+ * <code>#hashCode</code>, so that clients, like decoration managers, can recognize when they have
+ * two equal descriptors at hand, e.g. decorating an identical object.
+ * </p>
  * 
  * @see org.eclipse.jface.resource.ResourceManager
  * 
diff --git a/bundles/org.eclipse.ui/schema/decorators.exsd b/bundles/org.eclipse.ui/schema/decorators.exsd
index 494093e6b7c..e7741047246 100644
--- a/bundles/org.eclipse.ui/schema/decorators.exsd
+++ b/bundles/org.eclipse.ui/schema/decorators.exsd
@@ -74,6 +74,8 @@
 if &lt;b&gt;&lt;i&gt; lightweight&lt;/i&gt;&lt;/b&gt; is false or  &lt;samp&gt;org.eclipse.jface.viewers.ILightweightLabelDecorator&lt;/samp&gt; if lightweight is true. The default value is false. If there is no &lt;b&gt;&lt;i&gt;class&lt;/i&gt;&lt;/b&gt; element it is assumed to be lightweight.
 
 In the case where there is no decorator class this is said to be declarative. Declarative decorators with an enablement based on session properties, persistant properties or project description values (such as natures) will need to be updated explicitly when these values change using &lt;code&gt;IDecoratorManager#update()&lt;/code&gt;.
+&lt;br&gt;
+If the label decorator creates image descriptors for decorations, it must either ensure that the same instance is used for the same decorated object, or use an image descriptor implementation that  implements &lt;code&gt;#equals&lt;/code&gt; and &lt;code&gt;#hashCode&lt;/code&gt; accordingly.
                </documentation>
                <appinfo>
                   <meta.attribute kind="java" basedOn="org.eclipse.jface.viewers.ILabelDecorator"/>
@@ -93,7 +95,7 @@ In the case where there is no decorator class this is said to be declarative. De
          <attribute name="adaptable" type="boolean">
             <annotation>
                <documentation>
-                  a flag that indicates if types that can adapt to objects other than thier objectClass should use this object contribution.
+                  a flag that indicates if types that can adapt to objects other than their objectClass should use this object contribution.
 For non-lightweight decorators, this flag only has an effect if objectClass adapts to IResource.  For lightweight decorators, adaptability to any objectClass is supported as long as adaptability is defined through the adapter manager (see the class org.eclipse.runtime.IAdapterManager). Default value is false.
                </documentation>
             </annotation>
@@ -257,7 +259,6 @@ supplies an icon and a quadrant to apply that icon.
       </documentation>
    </annotation>
 
-
    <annotation>
       <appinfo>
          <meta.section type="implementation"/>
@@ -274,7 +275,7 @@ This is currently in use by the Resource Navigator.
          <meta.section type="copyright"/>
       </appinfo>
       <documentation>
-         Copyright (c) 2002, 2005 IBM Corporation and others.&lt;br&gt;
+         Copyright (c) 2002, 2014 IBM Corporation and others.&lt;br&gt;
 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 &lt;a