tweak comments

13 files changed, 49 insertions, 46 deletions

diff --git a/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/JpaDataSource.java b/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/JpaDataSource.java
index aa2699ac83..6610a45819 100644
--- a/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/JpaDataSource.java
+++ b/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/JpaDataSource.java
@@ -70,6 +70,12 @@ public interface JpaDataSource
 
 	/**
 	 * Select and return the table with the specified identifier.
+	 * We need this unusual method because the JPA spec does not allow columns
+	 * or join columns to specify a schema and/or catalog (which is only a
+	 * problem when an entity has two tables from different schemata but with
+	 * the same name).
+	 * 
+	 * @see org.eclipse.jpt.jpa.core.context.TypeMapping#resolveDbTable(String)
 	 */
 	Table selectTableForIdentifier(Iterable<Table> tables, String identifier);
 
diff --git a/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/JpaPlatform.java b/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/JpaPlatform.java
index d3cec2c329..31e90ffb19 100644
--- a/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/JpaPlatform.java
+++ b/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/JpaPlatform.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2006, 2010 Oracle. All rights reserved.
+ * Copyright (c) 2006, 2011 Oracle. All rights reserved.
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v1.0, which accompanies this distribution
  * and is available at http://www.eclipse.org/legal/epl-v10.html.
@@ -124,27 +124,24 @@ public interface JpaPlatform
 	// ********** resource types and definitions **********
 	
 	/**
-	 * Return true if the resource type is supported.  The result of this call is consistent with
-	 * the result of {@link #getResourceDefinition(JptResourceType)}
+	 * Return whether the platform supports the specified resource type.
+	 * This method is consistent with {@link #getResourceDefinition(JptResourceType)}.
 	 */
 	boolean supportsResourceType(JptResourceType resourceType);
 	
 	/**
-	 * Return a {@link ResourceDefinition} to describe the context model for a file of the given
-	 * resource type.
-	 * Throw an {@link IllegalArgumentException} if the resource type is not supported by the platform.
-	 * 
-	 * @param resourceType The resource type of a potential resource definition
-	 * @return The resource definition that can be used for such a file
+	 * Return the platform's resource definition for the specified resource type.
+	 * The returned definition describes the platform's corresponding context model.
+	 * Throw an {@link IllegalArgumentException} if the resource type is not
+	 * supported by the platform.
+	 * This method is consistent with {@link #supportsResourceType(JptResourceType)}.
 	 */
 	ResourceDefinition getResourceDefinition(JptResourceType resourceType);
 	
 	/**
-	 * Return the most recent supported {@link JptResourceType} for the given content type.
-	 * Throw an {@link IllegalArgumentException} if the content type is not supported by the platform.
-	 * 
-	 * @param contentType A content type supported by the platform
-	 * @return The most recent resource type supported by the platform
+	 * Return the most recent supported resource type for the specified content
+	 * type. Throw an {@link IllegalArgumentException} if the content type is not
+	 * supported by the platform.
 	 */
 	JptResourceType getMostRecentSupportedResourceType(IContentType contentType);
 	
diff --git a/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/context/MappingFile.java b/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/context/MappingFile.java
index 0e6602797d..e124d37299 100644
--- a/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/context/MappingFile.java
+++ b/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/context/MappingFile.java
@@ -39,12 +39,12 @@ public interface MappingFile
 
 	/**
 	 * Return the mapping file's root.
-	 * This can be null.
+	 * This can be <code>null</code>.
 	 */
 	MappingFileRoot getRoot();
 
 	/**
-	 * Return true if this mapping file exists in the given folder
+	 * Return whether the mapping file exists in the specified folder.
 	 */
 	boolean isIn(IFolder folder);
 
diff --git a/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/context/MultiRelationshipMapping.java b/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/context/MultiRelationshipMapping.java
index a7351fc176..d1b061a319 100644
--- a/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/context/MultiRelationshipMapping.java
+++ b/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/context/MultiRelationshipMapping.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2006, 2010 Oracle. All rights reserved.
+ * Copyright (c) 2006, 2011 Oracle. All rights reserved.
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v1.0, which accompanies this distribution
  * and is available at http://www.eclipse.org/legal/epl-v10.html.
@@ -10,7 +10,7 @@
 package org.eclipse.jpt.jpa.core.context;
 
 /**
- * Multi-valued (1:m, m:m) relationship mapping.
+ * Multi-valued relationship (1:m, m:m) mapping.
  * <p>
  * Provisional API: This interface is part of an interim API that is still
  * under development and expected to change significantly before reaching
diff --git a/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/context/SingleRelationshipMapping.java b/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/context/SingleRelationshipMapping.java
index 8a448c464c..cc2323fdcd 100644
--- a/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/context/SingleRelationshipMapping.java
+++ b/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/context/SingleRelationshipMapping.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2006, 2010 Oracle. All rights reserved.
+ * Copyright (c) 2006, 2011 Oracle. All rights reserved.
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v1.0, which accompanies this distribution
  * and is available at http://www.eclipse.org/legal/epl-v10.html.
@@ -10,7 +10,7 @@
 package org.eclipse.jpt.jpa.core.context;
 
 /**
- * JPA single (m:1, 1:2) mapping
+ * JPA single relationship (m:1, 1:1) mapping
  * <p>
  * Provisional API: This interface is part of an interim API that is still
  * under development and expected to change significantly before reaching
diff --git a/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/context/orm/OrmMultiRelationshipMapping.java b/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/context/orm/OrmMultiRelationshipMapping.java
index 6408e6f1a5..f7b62096f1 100644
--- a/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/context/orm/OrmMultiRelationshipMapping.java
+++ b/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/context/orm/OrmMultiRelationshipMapping.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2008, 2010 Oracle. All rights reserved.
+ * Copyright (c) 2008, 2011 Oracle. All rights reserved.
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v1.0, which accompanies this distribution
  * and is available at http://www.eclipse.org/legal/epl-v10.html.
@@ -13,7 +13,7 @@ import org.eclipse.jpt.jpa.core.context.MultiRelationshipMapping;
 import org.eclipse.jpt.jpa.core.resource.orm.AbstractXmlMultiRelationshipMapping;
 
 /**
- * <code>orm.xml</code> multi-valued (1:m, m:m) relationship mapping.
+ * <code>orm.xml</code> multi-valued relationship (1:m, m:m) mapping.
  * <p>
  * Provisional API: This interface is part of an interim API that is still
  * under development and expected to change significantly before reaching
diff --git a/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/jpa2/MetamodelSynchronizer.java b/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/jpa2/MetamodelSynchronizer.java
index 08a22a3bee..984d548f6d 100644
--- a/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/jpa2/MetamodelSynchronizer.java
+++ b/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/jpa2/MetamodelSynchronizer.java
@@ -58,7 +58,7 @@ public interface MetamodelSynchronizer {
 
 
 	/**
-	 * Singleton implemetation of the metamodel synchronizer interface that
+	 * Singleton implementation of the metamodel synchronizer interface that
 	 * does nothing. (Not sure we need this....)
 	 */
 	final class Null implements MetamodelSynchronizer, Serializable {
diff --git a/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/jpa2/context/orm/OrmPersistenceUnitMetadata2_0.java b/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/jpa2/context/orm/OrmPersistenceUnitMetadata2_0.java
index 13513392b3..60c158d4e6 100644
--- a/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/jpa2/context/orm/OrmPersistenceUnitMetadata2_0.java
+++ b/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/jpa2/context/orm/OrmPersistenceUnitMetadata2_0.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2010 Oracle. All rights reserved.
+ * Copyright (c) 2010, 2011 Oracle. All rights reserved.
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v1.0, which accompanies this distribution
  * and is available at http://www.eclipse.org/legal/epl-v10.html.
@@ -16,7 +16,7 @@ import org.eclipse.jpt.jpa.core.jpa2.context.MappingFilePersistenceUnitMetadata2
  * JPA 2.0
  * Context <code>orm.xml</code> persistence unit metadata.
  * Context model corresponding to the
- * XML resource model {@link XmlPersistenceUnitMetadata},
+ * XML resource model {@link org.eclipse.jpt.jpa.core.resource.orm.XmlPersistenceUnitMetadata},
  * which corresponds to the <code>persistence-unit-metadata</code> element
  * in the <code>orm.xml</code> file.
  * <p>
diff --git a/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/jpa2/context/orm/OrmSequenceGenerator2_0.java b/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/jpa2/context/orm/OrmSequenceGenerator2_0.java
index 773b945717..849a3dbf9c 100644
--- a/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/jpa2/context/orm/OrmSequenceGenerator2_0.java
+++ b/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/jpa2/context/orm/OrmSequenceGenerator2_0.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
-* Copyright (c) 2009, 2010 Oracle. All rights reserved.
+* Copyright (c) 2009, 2011 Oracle. All rights reserved.
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v1.0, which accompanies this distribution
 * and is available at http://www.eclipse.org/legal/epl-v10.html.
@@ -28,5 +28,5 @@ import org.eclipse.jpt.jpa.core.jpa2.context.SequenceGenerator2_0;
 public interface OrmSequenceGenerator2_0
 	extends SequenceGenerator2_0, OrmSequenceGenerator
 {
-	// nothing
+	// combine interfaces
 }
diff --git a/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/resource/java/BaseColumnAnnotation.java b/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/resource/java/BaseColumnAnnotation.java
index 7cee700993..3f9d3df4dd 100644
--- a/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/resource/java/BaseColumnAnnotation.java
+++ b/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/resource/java/BaseColumnAnnotation.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2007, 2010 Oracle. All rights reserved.
+ * Copyright (c) 2007, 2011 Oracle. All rights reserved.
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v1.0, which accompanies this distribution
  * and is available at http://www.eclipse.org/legal/epl-v10.html.
@@ -14,10 +14,10 @@ import org.eclipse.jpt.common.core.utility.TextRange;
 
 /**
  * Corresponds to the JPA annotations:<ul>
- * <li><code>javax.persistence.Column<code>
- * <li><code>javax.persistence.MapKeyColumn<code>
- * <li><code>javax.persistence.JoinColumn<code>
- * <li><code>javax.persistence.MapKeyJoinColumn<code>
+ * <li><code>javax.persistence.Column</code>
+ * <li><code>javax.persistence.MapKeyColumn</code>
+ * <li><code>javax.persistence.JoinColumn</code>
+ * <li><code>javax.persistence.MapKeyJoinColumn</code>
  * </ul>
  * Provisional API: This interface is part of an interim API that is still
  * under development and expected to change significantly before reaching
diff --git a/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/resource/java/BaseJoinColumnAnnotation.java b/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/resource/java/BaseJoinColumnAnnotation.java
index e0400e0a5e..ead44d01b9 100644
--- a/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/resource/java/BaseJoinColumnAnnotation.java
+++ b/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/resource/java/BaseJoinColumnAnnotation.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2007, 2010 Oracle. All rights reserved.
+ * Copyright (c) 2007, 2011 Oracle. All rights reserved.
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v1.0, which accompanies this distribution
  * and is available at http://www.eclipse.org/legal/epl-v10.html.
@@ -14,8 +14,8 @@ import org.eclipse.jpt.common.core.utility.TextRange;
 
 /**
  * Corresponds to the JPA annotations:<ul>
- * <li><code>javax.persistence.JoinColumn<code>
- * <li><code>javax.persistence.MapKeyJoinColumn<code>
+ * <li><code>javax.persistence.JoinColumn</code>
+ * <li><code>javax.persistence.MapKeyJoinColumn</code>
  * </ul>
  * Provisional API: This interface is part of an interim API that is still
  * under development and expected to change significantly before reaching
diff --git a/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/resource/java/CompleteColumnAnnotation.java b/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/resource/java/CompleteColumnAnnotation.java
index 15bfa6091a..883c4001de 100644
--- a/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/resource/java/CompleteColumnAnnotation.java
+++ b/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/resource/java/CompleteColumnAnnotation.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2007, 2010 Oracle. All rights reserved.
+ * Copyright (c) 2007, 2011 Oracle. All rights reserved.
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v1.0, which accompanies this distribution
  * and is available at http://www.eclipse.org/legal/epl-v10.html.
@@ -14,8 +14,8 @@ import org.eclipse.jpt.common.core.utility.TextRange;
 
 /**
  * Corresponds to the JPA annotations:<ul>
- * <li><code>javax.persistence.Column<code>
- * <li><code>javax.persistence.MapKeyColumn<code>
+ * <li><code>javax.persistence.Column</code>
+ * <li><code>javax.persistence.MapKeyColumn</code>
  * </ul>
  * Provisional API: This interface is part of an interim API that is still
  * under development and expected to change significantly before reaching
diff --git a/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/resource/java/NamedColumnAnnotation.java b/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/resource/java/NamedColumnAnnotation.java
index f6701fe0e3..dea6c02323 100644
--- a/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/resource/java/NamedColumnAnnotation.java
+++ b/jpa/plugins/org.eclipse.jpt.jpa.core/src/org/eclipse/jpt/jpa/core/resource/java/NamedColumnAnnotation.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2007, 2010 Oracle. All rights reserved.
+ * Copyright (c) 2007, 2011 Oracle. All rights reserved.
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v1.0, which accompanies this distribution
  * and is available at http://www.eclipse.org/legal/epl-v10.html.
@@ -14,13 +14,13 @@ import org.eclipse.jpt.common.core.utility.TextRange;
 
 /**
  * Corresponds to the JPA annotations:<ul>
- * <li><code>javax.persistence.Column<code>
- * <li><code>javax.persistence.MapKeyColumn<code>
- * <li><code>javax.persistence.JoinColumn<code>
- * <li><code>javax.persistence.MapKeyJoinColumn<code>
- * <li><code>javax.persistence.DiscriminatorColumn<code>
- * <li><code>javax.persistence.OrderColumn<code>
- * <li><code>javax.persistence.PrimaryKeyJoinColumn<code>
+ * <li><code>javax.persistence.Column</code>
+ * <li><code>javax.persistence.MapKeyColumn</code>
+ * <li><code>javax.persistence.JoinColumn</code>
+ * <li><code>javax.persistence.MapKeyJoinColumn</code>
+ * <li><code>javax.persistence.DiscriminatorColumn</code>
+ * <li><code>javax.persistence.OrderColumn</code>
+ * <li><code>javax.persistence.PrimaryKeyJoinColumn</code>
  * </ul>
  * Provisional API: This interface is part of an interim API that is still
  * under development and expected to change significantly before reaching