Javadoc refinements for Describable.

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

@@ -23,6 +23,7 @@
  */
 package hudson.model;
 
+import hudson.Extension;
 import jenkins.model.Jenkins;
 
 /**
@@ -31,7 +32,13 @@ import jenkins.model.Jenkins;
  * @author Kohsuke Kawaguchi
  */
 public abstract class AbstractDescribableImpl<T extends AbstractDescribableImpl<T>> implements Describable<T> {
+
+    /**
+     * By default looks for a nested class (conventionally named {@code DescriptorImpl}) implementing {@link Descriptor} and marked with {@link Extension}.
+     * <p>{@inheritDoc}
+     */
     public Descriptor<T> getDescriptor() {
         return Jenkins.getInstance().getDescriptorOrDie(getClass());
     }
+
 }

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

@@ -34,8 +34,9 @@ public interface Describable<T extends Describable<T>> {
      *
      * <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.
+     * implementation, so if {@code a.getClass() == b.getClass()} then by default
+     * {@code a.getDescriptor() == b.getDescriptor()} as well.
+     * (In rare cases a single implementation class may be used for instances with distinct descriptors.)
      */
     Descriptor<T> getDescriptor();
 }