some javadoc comments.
diff --git a/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/CompilationUnitHelper.java b/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/CompilationUnitHelper.java
index a1110d5..5ed0011 100644
--- a/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/CompilationUnitHelper.java
+++ b/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/CompilationUnitHelper.java
@@ -22,6 +22,8 @@
  * from pioneering adopters on the understanding that any code that uses this API will almost certainly be broken
  * (repeatedly) as the API evolves.
  * 
+ * <br><br> this code was taken from the JSP plugin.  This class is to ensure only one copy of the compilation unit exits.
+ * 
  * @author pavery
  */
 public class CompilationUnitHelper {
diff --git a/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/DocumentChangeListenerToTextEdit.java b/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/DocumentChangeListenerToTextEdit.java
index bbf9863..7320ba9 100644
--- a/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/DocumentChangeListenerToTextEdit.java
+++ b/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/DocumentChangeListenerToTextEdit.java
@@ -27,6 +27,12 @@
 * change significantly before reaching stability. It is being made 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.
+* <br><br>
+* 
+* this class attaches to a "cloned" document, listens for changes to that document then translates
+* the changes to text edits.  these changes can then be applied back to the original document.
+* 
+*
 */
 public class DocumentChangeListenerToTextEdit implements IDocumentListener {
 	private MultiTextEdit textEdit;
diff --git a/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/IJsTranslation.java b/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/IJsTranslation.java
index 67ebf63..5a6dd23 100644
--- a/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/IJsTranslation.java
+++ b/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/IJsTranslation.java
@@ -36,49 +36,132 @@
 * Provisional API: This class/interface is part of an interim API that is still under development and expected to
 * change significantly before reaching stability. It is being made 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.
+* (repeatedly) as the API evolves.<br>
+* 
 */
 public interface IJsTranslation {
 
+	/**
+	 * @return IJavaScriptProject that this translation belongs to
+	 */
 	public IJavaScriptProject getJavaProject();
 
+	/**
+	 * @return Original HTML document from the translation.
+	 */
 	public IDocument getHtmlDocument();
 
+	/**
+	 * @return integer position of a missing </script> tag (the document isn't well formed and resulted in translation error.).
+	 * 
+	 */
 	public int getMissingTagStart();
 
+	/**
+	 * @param javaPositionStart
+	 * @param javaPositionEnd
+	 * @return all javascript elements within the given range
+	 */
 	public IJavaScriptElement[] getAllElementsInJsRange(int javaPositionStart, int javaPositionEnd);
 
+	/**
+	 * @return the javascript unit from the jsdt.core
+	 */
 	public IJavaScriptUnit getCompilationUnit();
 
+	/**
+	 * @param javaPositionStart
+	 * @param javaPositionEnd
+	 * @return
+	 */
 	public IJavaScriptElement[] getElementsFromJsRange(int javaPositionStart, int javaPositionEnd);
 
+	/**
+	 * @return string of the document.
+	 */
 	public String getHtmlText();
 
+	/**
+	 * @param jsOffset
+	 * @return a single javascript element at the given offset.
+	 */
 	public IJavaScriptElement getJsElementAtOffset(int jsOffset);
 
+	/**
+	 * @return only the translated javascript text
+	 */
 	public String getJsText();
 
+	/**
+	 * @return a list of the script regions within the translation.
+	 */
 	public Position[] getScriptPositions();
 
+	/**
+	 * @param text
+	 */
 	public void insertInFirstScriptRegion(String text);
 
+	/**
+	 * insert javascript at the given offset.  method should ensure the documents well-formedness and proper script region.
+	 * 
+	 * @param offset
+	 * @param text
+	 */
 	public void insertScript(int offset, String text);
 
+	/**
+	 * @return a list of javascript errors
+	 */
 	public List getProblems();
 
+	/**
+	 * @param offset
+	 * @return if the offset is within a script import node.
+	 */
 	public boolean ifOffsetInImportNode(int offset);
 
+	/**
+	 * checks the CU for errors/consistancy.
+	 */
 	public void reconcileCompilationUnit();
 
+	/**
+	 * release the translation.  always a good idea to do when you're done.  you may notice document and model locks if not.
+	 */
 	public void release();
 	
+	/**
+	 * fixes a mangled html--> pure js name.
+	 * @param displayString
+	 * @return
+	 */
 	public String fixupMangledName(String displayString); 
 	
+	/**
+	 * start/stop collecting problems within the javascript unit.
+	 * @param collect
+	 */
 	public void setProblemCollectingActive(boolean collect);
 	
+	/**
+	 * @return
+	 */
 	public String getJavaPath();
 	
+	/**
+	 * 
+	 * 
+	 * @param htmlDocument
+	 * @param javaProj
+	 * @param listenForChanges
+	 * @return
+	 */
 	public IJsTranslation getInstance(IStructuredDocument htmlDocument, IJavaScriptProject javaProj, boolean listenForChanges) ;
 
+	/**
+	 * notify the translation to update any external dependancies that are created during translation
+	 * 
+	 */
 	public void classpathChange() ;
 }
\ No newline at end of file
diff --git a/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/IJsTranslator.java b/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/IJsTranslator.java
index 45011b9..8726cab 100644
--- a/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/IJsTranslator.java
+++ b/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/IJsTranslator.java
@@ -36,26 +36,65 @@
 */
 public interface IJsTranslator extends IDocumentListener{
 
+	/**
+	 * @return string of javascript from the document
+	 */
 	public String getJsText();
 
+	/**
+	 * sets the javascript unit buffer
+	 * @param buffer
+	 */
 	public void setBuffer(IBuffer buffer);
 
+	/**
+	 * 
+	 * @return a list of html locations within the docuemnt.
+	 */
 	public Position[] getHtmlLocations();
 
+	/**
+	 * @return the region of a missing </script> tag
+	 */
 	public int getMissingEndTagRegionStart();
 
+	/**
+	 * @return position array of <script src=".."> within the doc.
+	 */
 	public Position[] getImportHtmlRanges();
 
+	/**
+	 * @return raw/unresolved <script imports>
+	 */
 	public String[] getRawImports();
 
+	/**
+	 *  begin translating the document.
+	 */
 	public void translate();
 
+	/**
+	 * translates an inline (event="..") js container region and adds it to the document text.  must be called in order
+	 * @param container
+	 */
 	public void translateInlineJSNode(IStructuredDocumentRegion container);
 
+	/**
+	 * translates a script block.  must be called in the order it appears within the document.
+	 * @param container
+	 */
 	public void translateJSNode(IStructuredDocumentRegion container);
 
+	/**
+	 * translates a <script src=".."> element, parsing out an import.
+	 * @param region
+	 */
 	public void translateScriptImportNode(IStructuredDocumentRegion region);
 
+	/**
+	 * release any resources the translation is holding onto.
+	 * 
+	 */
 	public void release();
 
 }
\ No newline at end of file
diff --git a/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/JsTranslationAdapter.java b/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/JsTranslationAdapter.java
index 5c167ff..4bcfea4 100644
--- a/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/JsTranslationAdapter.java
+++ b/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/JsTranslationAdapter.java
@@ -45,6 +45,7 @@
 * from pioneering adopters on the understanding that any code that uses this API will almost certainly be broken
 * (repeatedly) as the API evolves.
 
+ * <br><br> this adapter loads translation information from extension points.  this is to allow more complicated html/js translations through extensions.
  * @author pavery
  */
 public class JsTranslationAdapter implements INodeAdapter, IResourceChangeListener {
diff --git a/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/IndexWorkspaceJob.java b/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/IndexWorkspaceJob.java
index 28010a7..fc3b6e1 100644
--- a/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/IndexWorkspaceJob.java
+++ b/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/IndexWorkspaceJob.java
@@ -34,7 +34,7 @@
 * change significantly before reaching stability. It is being made 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.
-*
+* (copied from JSP)
  * Re-indexes the entire workspace.
  * Ensures the JSP Index is in a stable state before performing a search.
  * (like after a crash or if previous indexing was canceled)
diff --git a/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/JSDTSearchDocumentDelegate.java b/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/JSDTSearchDocumentDelegate.java
index a477be9..a4c0874 100644
--- a/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/JSDTSearchDocumentDelegate.java
+++ b/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/JSDTSearchDocumentDelegate.java
@@ -22,7 +22,7 @@
 * change significantly before reaching stability. It is being made 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.
-*
+*(copied from JSP)
  * Wrapper method to set getPath() path to be the path of the compilation unit 
  * for the jsp file. (since it's a final method, it needs to be set via constructor)
  * 
diff --git a/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/JsIndexManager.java b/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/JsIndexManager.java
index a445660..4025b94 100644
--- a/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/JsIndexManager.java
+++ b/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/JsIndexManager.java
@@ -54,7 +54,7 @@
 * change significantly before reaching stability. It is being made 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.
-*
+*(copied from JSP)
  * Responsible for keeping the JSP index up to date.
  * 
  * @author pavery
diff --git a/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/JsPathIndexer.java b/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/JsPathIndexer.java
index 213071e..c697a15 100644
--- a/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/JsPathIndexer.java
+++ b/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/JsPathIndexer.java
@@ -31,7 +31,7 @@
 * change significantly before reaching stability. It is being made 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.
-*
+*(copied from JSP)
  * pa_TODO Still need to take into consideration:
  * 	- focus in workspace
  *  - search pattern
diff --git a/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/JsSearchDocument.java b/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/JsSearchDocument.java
index 1270efb..c1a989e 100644
--- a/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/JsSearchDocument.java
+++ b/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/JsSearchDocument.java
@@ -39,7 +39,7 @@
 * change significantly before reaching stability. It is being made 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.
-*
+*(copied from JSP)
  * Created with a .jsp file, but should appear to be a .java file for indexing
  * and searching purposes. There are purposely few fields in this class, and
  * those fields are lightweight since it's possible for many JSP search
diff --git a/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/JsSearchParticipant.java b/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/JsSearchParticipant.java
index 7965f0e..88ac3a1 100644
--- a/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/JsSearchParticipant.java
+++ b/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/JsSearchParticipant.java
@@ -32,7 +32,7 @@
 * change significantly before reaching stability. It is being made 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.
-*
+*(copied from JSP)
  * Integration of JSP w/ java search.
  * 
  * @author pavery
diff --git a/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/JsSearchScope.java b/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/JsSearchScope.java
index d220965..4fe87fb 100644
--- a/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/JsSearchScope.java
+++ b/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/JsSearchScope.java
@@ -25,7 +25,7 @@
 * change significantly before reaching stability. It is being made 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.
-*
+*(copied from JSP)
  * Used to constrain JSP/java search to certain paths and elements.
  * @author pavery
  */
diff --git a/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/JsSearchSupport.java b/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/JsSearchSupport.java
index 74f4ffd..81a5ffc 100644
--- a/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/JsSearchSupport.java
+++ b/bundles/org.eclipse.wst.jsdt.web.core/src/org/eclipse/wst/jsdt/web/core/javascript/search/JsSearchSupport.java
@@ -46,7 +46,7 @@
 * change significantly before reaching stability. It is being made 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.
-*
+*(copied from JSP)
  * Central access to java indexing and search. All contact between JDT indexing
  * and Searching should be done through here.
  *