add some doc to AttributeContainer

hibernate-core/src/main/java/org/hibernate/mapping/AttributeContainer.java

@@ -7,12 +7,24 @@
 package org.hibernate.mapping;
 
 /**
- * Identifies a mapping model object which may have {@linkplain Property attributes} (fields or properties).
- * Abstracts over {@link PersistentClass} and {@link Join}.
+ * Identifies a mapping model object which may have {@linkplain Property attributes}
+ * (fields or properties). Abstracts over {@link PersistentClass} and {@link Join}.
+ *
+ * @apiNote This model makes sense in {@code hbm.xml} mappings where a
+ *          {@code <property/>} element may occur as a child of a {@code <join/>}.
+ *          In annotations, and in {@code orm.xml}, a property cannot be said to
+ *          itself belong to a secondary table, instead its columns are mapped to
+ *          the table explicitly. In fact, the old {@code hbm.xml} model was more
+ *          natural when it came to handling {@code <column/>} and especially
+ *          {@code <formula/>} mappings in secondary tables. There was no need to
+ *          repetitively write {@code @Column(table="secondary")}. Granted, it does
+ *          sound strange to say that a Java property "belongs" to a secondary table.
  *
  * @author Steve Ebersole
  */
-//NOTE: this unifying contract is currently only used from HBM binding and so only defines the needs of that use case.
 public interface AttributeContainer {
+	/**
+	 * Add a property to this {@link PersistentClass} or {@link Join}.
+	 */
 	void addProperty(Property attribute);
 }