229838 - a few minor javadoc changes, including adding the provisional api comment to JpaPlatform, this was an oversight

4 files changed, 29 insertions, 14 deletions

diff --git a/jpa/plugins/org.eclipse.jpt.core/src/org/eclipse/jpt/core/JpaFactory.java b/jpa/plugins/org.eclipse.jpt.core/src/org/eclipse/jpt/core/JpaFactory.java
index 5ed0e0ac17..7ba14028ea 100644
--- a/jpa/plugins/org.eclipse.jpt.core/src/org/eclipse/jpt/core/JpaFactory.java
+++ b/jpa/plugins/org.eclipse.jpt.core/src/org/eclipse/jpt/core/JpaFactory.java
@@ -163,6 +163,7 @@ public interface JpaFactory
 	
 	/**
 	 * Return true if a resource model will be provided for the given file
+	 * (this method should be moved to JpaPlatform)
 	 */
 	boolean hasRelevantContent(IFile file);
 	
diff --git a/jpa/plugins/org.eclipse.jpt.core/src/org/eclipse/jpt/core/JpaFile.java b/jpa/plugins/org.eclipse.jpt.core/src/org/eclipse/jpt/core/JpaFile.java
index 73868f9448..ca1473ff10 100644
--- a/jpa/plugins/org.eclipse.jpt.core/src/org/eclipse/jpt/core/JpaFile.java
+++ b/jpa/plugins/org.eclipse.jpt.core/src/org/eclipse/jpt/core/JpaFile.java
@@ -14,7 +14,9 @@ import org.eclipse.core.resources.IFile;
 import org.eclipse.jdt.core.ElementChangedEvent;
 
 /**
- * 
+ * A JpaProject contains Jpa files for all IFiles in the project that
+ * are relevant to the JpaPlatform.
+ * @see JpaFactory#hasRelevantContent(IFile), this method should be moved to JpaPlatform
  * 
  * Provisional API: This interface is part of an interim API that is still
  * under development and expected to change significantly before reaching
@@ -65,20 +67,26 @@ public interface JpaFile extends JpaNode
 	String ROOT_STRUCTURE_NODES_COLLECTION = "rootStructureNodes";
 	
 	/**
-	 * Return the root context model object represented by this JPA file.
+	 * Return the root context model objects represented by this JPA file.
 	 */
 	Iterator<JpaStructureNode> rootStructureNodes();
 	
+	/**
+	 * Return the number of root context model objects represented by this JPA file.
+	 */
 	int rootStructureNodesSize();
 
 	/**
-	 * Set the root context model object represented by this JPA file.
+	 * Add a root context model object represented by this JPA file.
 	 * There is the potential for multiple root structure nodes 
-	 * for this JPA file.  For example a java file that is listed
+	 * for a particular key.  For example a java file that is listed
 	 * both as a <class> in the persistence.xml and as an <entity> in
 	 * an orm.xml file.  In this case the orm.xml file needs to set
 	 * the root structure node after the java class reference.
 	 * Last one in during project update wins.
+	 * 
+	 * Call removeRootStructureNode(Object) to clean up when a file is
+	 * deleted.
 	 */
 	void addRootStructureNode(Object key, JpaStructureNode rootStructureNode);	
 	
diff --git a/jpa/plugins/org.eclipse.jpt.core/src/org/eclipse/jpt/core/JpaPlatform.java b/jpa/plugins/org.eclipse.jpt.core/src/org/eclipse/jpt/core/JpaPlatform.java
index 7b0656b6b1..7ebc79fbf4 100644
--- a/jpa/plugins/org.eclipse.jpt.core/src/org/eclipse/jpt/core/JpaPlatform.java
+++ b/jpa/plugins/org.eclipse.jpt.core/src/org/eclipse/jpt/core/JpaPlatform.java
@@ -27,6 +27,12 @@ import org.eclipse.wst.validation.internal.provisional.core.IMessage;
  * as necessary.
  * 
  * See the org.eclipse.jpt.core.jpaPlatform extension point
+ * 
+ * Provisional API: This interface is part of an interim API that is still
+ * under development and expected to change significantly before reaching
+ * stability. It is available at this early stage to solicit feedback from
+ * pioneering adopters on the understanding that any code that uses this API
+ * will almost certainly be broken (repeatedly) as the API evolves.
  */
 public interface JpaPlatform
 {
@@ -57,8 +63,8 @@ public interface JpaPlatform
 	JpaFile buildJpaFile(JpaProject jpaProject, IFile file);
 	
 	/**
-	 * Return a factory responsible for creating core (e.g. IJpaProject), resource
-	 * (e.g. PersistenceResource), and context (e.g. IPersistenceUnit) model
+	 * Return a factory responsible for creating core (e.g. JpaProject), resource
+	 * (e.g. PersistenceResource), and context (e.g. PersistenceUnit) model
 	 * objects
 	 */
 	JpaFactory getJpaFactory();
@@ -78,7 +84,7 @@ public interface JpaPlatform
 	/**
 	 * Build a Java type mapping with the given mapping key and parent.  Throws a IllegalArgumentException
 	 * if the typeMappingKey is not supported by this platform.
-	 * Override {@link #GenericJpaPlatform.addJavaTypeMappingProvidersTo(Collection<IJavaTypeMappingProvider>)}
+	 * Override {@link #GenericJpaPlatform.addJavaTypeMappingProvidersTo(Collection<JavaTypeMappingProvider>)}
 	 * to add new supported type mappings to the platform
 	 */
 	JavaTypeMapping buildJavaTypeMappingFromMappingKey(String typeMappingKey, JavaPersistentType parent);
@@ -86,7 +92,7 @@ public interface JpaPlatform
 	/**
 	 * Build a Java type mapping with the given mapping annotation and parent.  Throws a IllegalArgumentException
 	 * if the mapping annotation is not supported by this platform.
-	 * Override {@link #GenericJpaPlatform.addJavaTypeMappingProvidersTo(Collection<IJavaTypeMappingProvider>)}
+	 * Override {@link #GenericJpaPlatform.addJavaTypeMappingProvidersTo(Collection<JavaTypeMappingProvider>)}
 	 * to add new supported type mappings to the platform
 	 */
 	JavaTypeMapping buildJavaTypeMappingFromAnnotation(String mappingAnnotationName, JavaPersistentType parent);
@@ -96,7 +102,7 @@ public interface JpaPlatform
 	/**
 	 * Build a Java attribute mapping with the given mapping key and parent.  Throws a IllegalArgumentException
 	 * if the attributeMappingKey is not supported by this platform.
-	 * Override {@link #GenericJpaPlatform.addJavaAttributeMappingProvidersTo(Collection<IJavaAttributeMappingProvider>)}
+	 * Override {@link #GenericJpaPlatform.addJavaAttributeMappingProvidersTo(Collection<JavaAttributeMappingProvider>)}
 	 * to add new supported attribute mappings to the platform
 	 */
 	JavaAttributeMapping buildJavaAttributeMappingFromMappingKey(String attributeMappingKey, JavaPersistentAttribute parent);
@@ -104,7 +110,7 @@ public interface JpaPlatform
 	/**
 	 * Build a Java attribute mapping with the given mapping annotation and parent.  Throws a IllegalArgumentException
 	 * if the mapping annotation is not supported by this platform.
-	 * Override {@link #GenericJpaPlatform.addJavaAttributeMappingProvidersTo(Collection<IJavaAttributeMappingProvider>)}
+	 * Override {@link #GenericJpaPlatform.addJavaAttributeMappingProvidersTo(Collection<JavaAttributeMappingProvider>)}
 	 * to add new supported attribute mappings to the platform
 	 */
 	JavaAttributeMapping buildJavaAttributeMappingFromAnnotation(String mappingAnnotationName, JavaPersistentAttribute parent);
@@ -112,7 +118,7 @@ public interface JpaPlatform
 	/**
 	 * Build a default Java attribute mapping with the given mapping annotation and parent.  Throws a IllegalArgumentException
 	 * if the mapping annotation is not supported by this platform.
-	 * Override {@link #GenericJpaPlatform.addDefaultJavaAttributeMappingProvidersTo(Collection<IDefaultJavaAttributeMappingProvider>)}
+	 * Override {@link #GenericJpaPlatform.addDefaultJavaAttributeMappingProvidersTo(Collection<DefaultJavaAttributeMappingProvider>)}
 	 * to add new supported attribute mappings to the platform
 	 */
 	JavaAttributeMapping buildDefaultJavaAttributeMapping(JavaPersistentAttribute parent);
@@ -120,7 +126,7 @@ public interface JpaPlatform
 	/**
 	 * Return the attribute mapping key corresponding to the default atribute mapping
 	 * that applies to the Java persistent attribute.  This will be based on the attribute's
-	 * type.  See {@link IDefaultJavaAttributeMappingProvider.#defaultApplies(IJavaPersistentAttribute)}
+	 * type.  See {@link DefaultJavaAttributeMappingProvider.#defaultApplies(JavaPersistentAttribute)}
 	 */
 	String defaultJavaAttributeMappingKey(JavaPersistentAttribute persistentAttribute);
 	
diff --git a/jpa/plugins/org.eclipse.jpt.core/src/org/eclipse/jpt/core/JpaStructureNode.java b/jpa/plugins/org.eclipse.jpt.core/src/org/eclipse/jpt/core/JpaStructureNode.java
index dba9e375a6..13acbcb8f6 100644
--- a/jpa/plugins/org.eclipse.jpt.core/src/org/eclipse/jpt/core/JpaStructureNode.java
+++ b/jpa/plugins/org.eclipse.jpt.core/src/org/eclipse/jpt/core/JpaStructureNode.java
@@ -15,7 +15,7 @@ import org.eclipse.jpt.core.utility.TextRange;
 /**
  * Implement this interface for objects that appear in the Structure view
  * This is used by JpaSelection to determine selection in the editor.
- * Details pages are also provided for each IJpaStructureNode.
+ * Details pages are also provided for each JpaStructureNode.
  * 
  * I did not implement JpaContextNode and I'm not even sure we should implement
  * JpaNode.  It is possibly someone could want a structure node that is
@@ -35,7 +35,7 @@ public interface JpaStructureNode extends JpaNode
 	JpaStructureNode getStructureNode(int textOffset);
 	
 	/**
-	 * Return the text range do be used to select text in the editor
+	 * Return the text range to be used to select text in the editor
 	 * corresponding to this node.
 	 */
 	TextRange getSelectionTextRange();