improving the doc as suggested by Eric.

git-svn-id: https://hudson.dev.java.net/svn/hudson/trunk/hudson/main@1978 71c3de6d-444a-0410-be80-ed276b4c234a

core/src/main/java/hudson/model/Describable.java

@@ -8,6 +8,11 @@ package hudson.model;
 public interface Describable<T extends Describable<T>> {
     /**
      * Gets the descriptor for this instance.
+     *
+     * <p>
+     * {@link Descriptor} is a singleton for every concrete {@link Describable}
+     * implementation, so if <tt>a.getClass()==b.getClass()</tt> then
+     * <tt>a.getDescriptor()==b.getDescriptor()</tt> must hold.
      */
     Descriptor<T> getDescriptor();
 }

core/src/main/java/hudson/model/Descriptor.java

@@ -19,7 +19,10 @@ import java.util.logging.Logger;
  *
  * <p>
  * {@link Descriptor} is an object that has metadata about a {@link Describable}
- * object, and also serves as a factory. A {@link Descriptor}/{@link Describable}
+ * object, and also serves as a factory (in a way this relationship is similar
+ * to {@link Object}/{@link Class} relationship.
+ *
+ * A {@link Descriptor}/{@link Describable}
  * combination is used throughout in Hudson to implement a
  * configuration/extensibility mechanism.
  *