Doc improvements

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

@@ -910,6 +910,9 @@ List<T> newInstancesFromHeteroList(StaplerRequest req, Object formData,
             for (Object o : JSONArray.fromObject(formData)) {
                 JSONObject jo = (JSONObject)o;
                 Descriptor<T> d = null;
+                // 'kind' and '$class' are mutually exclusive (see class-entry.jelly), but to be more lenient on the reader side,
+                // we check them both anyway. 'kind' (which maps to ID) is more unique than '$class', which can have multiple matching
+                // Descriptors, so we prefer 'kind' if it's present.
                 String kind = jo.optString("kind", null);
                 if (kind != null) {
                     d = findById(descriptors, kind);

core/src/main/resources/lib/form/class-entry.jelly

@@ -26,6 +26,16 @@ THE SOFTWARE.
          xmlns:l="/lib/layout" xmlns:t="/lib/hudson" xmlns:f="/lib/form">
   <st:documentation>
     Invisible &lt;f:entry> type for embedding a descriptor's $class field.
+
+    Most of the time a Descriptor has an unique class name that we can use to instantiate the right Describable
+    class, so we use the '$class' to represent that to clarify the intent.
+
+    In some other times, such as templates, there are multiple Descriptors with the same Descriptor.clazz
+    but different IDs, and in that case we put 'kind' to indicate that. In this case, to avoid confusing
+    readers we do not put non-unique '$class'.
+
+    See Descriptor.newInstancesFromHeteroList for how the reader side is handled.
+
     <st:attribute name="clazz">
       The describable class that we are instantiating via structured form submission.
     </st:attribute>