Bug 289116 -  The JSDI interfaces need to be documented

bundles/org.eclipse.e4.languages.javascript.debug.jsdi/src/org/eclipse/e4/languages/javascript/jsdi/ScriptReference.java

diff --git a/bundles/org.eclipse.e4.languages.javascript.debug.jsdi/src/org/eclipse/e4/languages/javascript/jsdi/ScriptReference.java b/bundles/org.eclipse.e4.languages.javascript.debug.jsdi/src/org/eclipse/e4/languages/javascript/jsdi/ScriptReference.java
index 2cd77c1..d0d0f6e 100644
--- a/bundles/org.eclipse.e4.languages.javascript.debug.jsdi/src/org/eclipse/e4/languages/javascript/jsdi/ScriptReference.java
+++ b/bundles/org.eclipse.e4.languages.javascript.debug.jsdi/src/org/eclipse/e4/languages/javascript/jsdi/ScriptReference.java
@@ -3,19 +3,83 @@
 import java.util.List;
 import java.util.Map;
 
+/**
+ * Describes a JavaScript script object. A script object has location information for all of the lines and functions contained within it.
+ * 
+ * @since 0.9
+ */
 public interface ScriptReference extends Mirror {
 
-	public List allLineLocations();
+	/**
+	 * Returns the complete live list of line locations in this script. <br>
+	 * <br>
+	 * This method can return <code>null</code>.
+	 * 
+	 * @return the line locations in this script
+	 * @see Location
+	 * @see #lineLocation(int)
+	 */
+	public List/* <Location> */allLineLocations();
 
+	/**
+	 * Returns the {@link Location} information for the given line number in this script.<br>
+	 * <br>
+	 * This method can return <code>null</code>.
+	 * 
+	 * @param lineNumber
+	 * @return the {@link Location} information for the given line number.
+	 * @see Location
+	 * @see #allLineLocations()
+	 */
 	public Location lineLocation(int lineNumber);
 
-	public List allFunctionLocations();
+	/**
+	 * Returns the complete live list of function locations in this script.<br>
+	 * <br>
+	 * This method can return <code>null</code>.
+	 * 
+	 * @return the function locations in this script
+	 * @see Location
+	 * @see #functionLocation(String)
+	 */
+	public List/* <Location> */allFunctionLocations();
 
+	/**
+	 * Returns the {@link Location} information for a function with the given name in this script.<br>
+	 * <br>
+	 * This method can return <code>null</code>.
+	 * 
+	 * @param functionName
+	 * @return the {@link Location} information for a function with the given name
+	 * @see Location
+	 * @see #allFunctionLocations()
+	 */
 	public Location functionLocation(String functionName);
 
+	/**
+	 * Returns the entire known source for this script at the time this method is called.<br>
+	 * <br>
+	 * This method can return <code>null</code>.
+	 * 
+	 * @return the source for this script
+	 */
 	public String source();
 
+	/**
+	 * Returns the path to the source of this script.<br>
+	 * <br>
+	 * This method can return <code>null</code>.
+	 * 
+	 * @return the path to the source of this script
+	 */
 	public String sourcePath();
 
+	/**
+	 * Returns a mapping of additional properties describing the source for this script.<br>
+	 * <br>
+	 * This method can return <code>null</code>.
+	 * 
+	 * @return a mapping of additional source properties for this script
+	 */
 	public Map sourceProperties();
 }