miscellaneous javadoc changes, add some empty array constants to IIndex* interfaces

core/org.eclipse.cdt.core/parser/org/eclipse/cdt/core/index/IIndexLinkage.java

@@ -29,4 +29,9 @@ import org.eclipse.cdt.core.dom.ILinkage;
  * @since 4.0
  */
 public interface IIndexLinkage extends ILinkage {
+	/**
+	 * Empty IIndexLinkage array constant
+	 * @since 4.0.1
+	 */
+	IIndexLinkage[] EMPTY_INDEX_LINKAGE_ARRAY= new IIndexLinkage[0];
 }

core/org.eclipse.cdt.core/parser/org/eclipse/cdt/core/index/provider/IIndexProvider.java

@@ -16,6 +16,7 @@ import org.eclipse.core.runtime.CoreException;
 /**
  * An IIndexProvider implementation provides additional indexing information for CDT projects
  * This interface only exists to hold commonality from sub-interfaces.
+ * @since 4.0.0
  */
 public interface IIndexProvider {
 	/**
@@ -25,9 +26,6 @@ public interface IIndexProvider {
 	 * <p>
 	 * The method will only be called once per project per eclipse session. This method will be called when a project is deleted
 	 * and a new project of the same name added. It also may be called lazily (at the point of first logical index use).
-	 * <p>
-	 * It is also expected the provider implementation will want to watch some properties of the project to determine
-	 * what index content to provide.
 	 * @param project
 	 * @return
 	 */

core/org.eclipse.cdt.core/parser/org/eclipse/cdt/core/index/provider/IPDOMDescriptor.java

@@ -14,7 +14,8 @@ import org.eclipse.cdt.core.index.IIndexLocationConverter;
 import org.eclipse.core.runtime.IPath;
 
 /**
- * 
+ * Describes a PDOM format file in the local file system.
+ * @since 4.0.0
  */
 public interface IPDOMDescriptor {
 	/**

core/org.eclipse.cdt.core/parser/org/eclipse/cdt/core/index/provider/IReadOnlyPDOMProvider.java

@@ -14,14 +14,14 @@ import org.eclipse.cdt.core.settings.model.ICConfigurationDescription;
 
 /**
  * This interface is intended for ISVs to implement when plugging a mechanism
- * for read-only/offline indexes into the CIndex.ReadOnlyPDOMProvider extension point element.
+ * for read-only/off-line indexes into the CIndex.ReadOnlyPDOMProvider extension point element.
+ * @since 4.0.0
  */
 public interface IReadOnlyPDOMProvider extends IIndexProvider {
 	/**
-	 * Returns the descriptors 
-	 * @param cproject
-	 * @param config
-	 * @return
+	 * Returns an array of IPDOMDescriptors that should contribute to the logical index
+	 * for the specified {@link ICConfigurationDescription}
+	 * @param config the configuration description whose logical index should be augmented
 	 */
 	public IPDOMDescriptor[] getDescriptors(ICConfigurationDescription config);
 }

core/org.eclipse.cdt.core/parser/org/eclipse/cdt/internal/core/index/IIndexFragmentInclude.java

@@ -15,7 +15,12 @@ import org.eclipse.cdt.core.index.IIndexInclude;
 import org.eclipse.core.runtime.CoreException;
 
 public interface IIndexFragmentInclude extends IIndexInclude {
-
+	/**
+	 * Empty array constant
+	 * @since 4.0.1
+	 */
+	IIndexFragmentInclude[] EMPTY_FRAGMENT_INCLUDES_ARRAY = new IIndexFragmentInclude[0];
+	
 	/**
 	 * Returns the fragment that owns this include.
 	 */

core/org.eclipse.cdt.core/parser/org/eclipse/cdt/internal/core/index/IndexFactory.java

@@ -37,7 +37,7 @@ import org.eclipse.core.resources.IProject;
 import org.eclipse.core.runtime.CoreException;
 
 /**
- * Class that creates indexes based on pdoms
+ * Class that creates indexes based on PDOMs
  * @since 4.0
  */
 public class IndexFactory {
@@ -192,7 +192,7 @@ public class IndexFactory {
 	}
 	
 	/**
-	 * Add an entry for the specified fragment. This copes with problems occuring when reading
+	 * Add an entry for the specified fragment. This copes with problems occurring when reading
 	 * the fragment ID.
 	 * @param id2fragment the map to add the entry to
 	 * @param fragment the fragment or null (which will result in no action)

core/org.eclipse.cdt.core/src/org/eclipse/cdt/core/CCorePlugin.java

@@ -78,6 +78,9 @@ import org.eclipse.core.runtime.content.IContentType;
 import org.eclipse.core.runtime.jobs.Job;
 import org.osgi.framework.BundleContext;
 
+/**
+ * CCorePlugin is the life-cycle owner of the core plug-in, and starting point for access to many core APIs.
+ */
 public class CCorePlugin extends Plugin {
 
 	public static final int STATUS_CDTPROJECT_EXISTS = 1;
@@ -342,7 +345,7 @@ public class CCorePlugin extends Plugin {
         
         // bug 186755, when started after the platform has been started the job manager
         // is no longer suspended. So we have to start a job at the very end to make
-        // sure we don't trigger a concurrent plugin activation from within the job.
+        // sure we don't trigger a concurrent plug-in activation from within the job.
 		post1.schedule();
 		post2.schedule();
 	}
@@ -1040,7 +1043,7 @@ public class CCorePlugin extends Plugin {
 	//private static final String CONTENTASSIST = CCorePlugin.PLUGIN_ID + "/debug/contentassist" ; //$NON-NLS-1$
 
 	/**
-	 * Configure the plugin with respect to option settings defined in ".options" file
+	 * Configure the plug-in with respect to option settings defined in ".options" file
 	 */
 	public void configurePluginDebugOptions() {
 		
@@ -1208,7 +1211,7 @@ public class CCorePlugin extends Plugin {
 	}
 	
 	/**
-	 * aswers whether the given project is a new-style project, i.e. CConfigurationDataProvider-driven
+	 * Answers whether the given project is a new-style project, i.e. CConfigurationDataProvider-driven
 	 * @param project
 	 * @return
 	 */
@@ -1217,7 +1220,7 @@ public class CCorePlugin extends Plugin {
 	}
 
 	/**
-	 * aswers whether the given project is a new-style project, i.e. CConfigurationDataProvider-driven
+	 * Answers whether the given project is a new-style project, i.e. CConfigurationDataProvider-driven
 	 * @param des
 	 * @return
 	 */