add missing javadoc

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

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2006 Symbian Software Ltd. and others.
+ * Copyright (c) 2006, 2007 Symbian Software Ltd. and others.
  * 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
@@ -22,6 +22,14 @@ import org.eclipse.core.runtime.Path;
 /**
  * Factory for obtaining instances of IIndexFileLocation for workspace or external files, and
  * some utility methods for going in the opposite direction. 
+ * 
+ * <strong>EXPERIMENTAL</strong>. This class or interface has been added as
+ * part of a work in progress. There is no guarantee that this API will work or
+ * that it will remain the same. Please do not use this API without consulting
+ * with the CDT team.
+ * </p>
+ * 
+ * @since 4.0
  */
 public class IndexLocationFactory {
 	/**
@@ -46,13 +54,28 @@ public class IndexLocationFactory {
 	/**
 	 * Returns the absolute file path of an URI or null if the 
 	 * URI is not a filesystem path.
-	 * @param uri
+	 * @param uri 
-	 * @return
+	 * @return the absolute file path of an URI or null if the 
+	 * URI is not a filesystem path.
 	 */
 	public static IPath getAbsolutePath(IIndexFileLocation location) {
 		return URIUtil.toPath(location.getURI());
 	}
 	
+	/**
+	 * Returns an IIndexFileLocation by searching the workspace for resources that are mapped
+	 * onto the specified absolute path.
+	 * <p>
+	 * If such a resource exists, an IIndexFileLocation that
+	 * contains both the resource location URI, and the resources full path is created.
+	 * <p>
+	 * Otherwise, an IIndexFileLocation which contains the absolute path in URI form is returned.
+	 * <p>
+	 * N.B. As this searches the workspace, following links and potentially reading from alternate
+	 * file systems, this method may be expensive.
+	 * @param absolutePath
+	 * @return an IIndexFileLocation for the specified resource, containing a workspace relative path if possible.
+	 */
 	public static IIndexFileLocation getIFLExpensive(String absolutePath) {
 		IFile[] files = ResourcesPlugin.getWorkspace().getRoot().findFilesForLocation(new Path(absolutePath));
 		if(files.length==1) {
@@ -61,14 +84,29 @@ public class IndexLocationFactory {
 		return new IndexFileLocation(URIUtil.toURI(absolutePath), null);
 	}
 	
+	/**
+	 * Returns an IIndexFileLocation for the specified absolute path, with no associated full path.
+	 * @param absolutePath
+	 * @return an IIndexFileLocation for the specified absolute path, with no associated full path.
+	 */
 	public static IIndexFileLocation getExternalIFL(String absolutePath) {
 		return getExternalIFL(new Path(absolutePath));
 	}
 	
+	/**
+	 * Returns an IIndexFileLocation for the specified absolute path, with no associated full path.
+	 * @param absolutePath
+	 * @return an IIndexFileLocation for the specified absolute path, with no associated full path.
+	 */
 	public static IIndexFileLocation getExternalIFL(IPath absolutePath) {
 		return new IndexFileLocation(URIUtil.toURI(absolutePath), null);	
 	}
 	
+	/**
+	 * Returns an IIndexFileLocation for the specified workspace file
+	 * @param file
+	 * @return an IIndexFileLocation for the specified workspace file
+	 */
 	public static IIndexFileLocation getWorkspaceIFL(IFile file) {
 		return new IndexFileLocation(file.getLocationURI(), file.getFullPath().toString());
 	}
@@ -80,7 +118,7 @@ public class IndexLocationFactory {
 	 * <li> null, in any other case
 	 * </ul>
 	 * @param tu
-	 * @return
+	 * @return a suitable IIndexFileLocation for the specified ITranslationUnit
 	 */
 	public static IIndexFileLocation getIFL(ITranslationUnit tu) {
 		IResource res = tu.getResource();