Add JavaDoc to src/ public dom packages.

core/org.eclipse.cdt.core/src/org/eclipse/cdt/core/dom/CDOM.java

@@ -26,19 +26,36 @@ import org.eclipse.core.resources.IFile;
  */
 public class CDOM implements IASTServiceProvider {
     
+    /**
+     * Singleton - Constructor is private.
+     */
     private CDOM() 
     {
     }
     
+    /**
+     * <code>instance</code> is the singleton.
+     */
     private static CDOM instance = new CDOM();
+    
+    /**
+     * accessor for singleton instance
+     * @return instance
+     */
     public static CDOM getInstance()
     {
         return instance;
     }
     
+    /**
+     * Currently, only one AST Service is provided.  
+     */
     private IASTServiceProvider defaultService = new InternalASTServiceProvider();    
 
     
+    /**
+     * @return IASTServiceProvider, the mechanism for obtaining an AST
+     */
     public IASTServiceProvider getASTService() {
         //CDOM itself is not so much "the" AST service as it acts as a proxy 
         //to different AST services
@@ -50,11 +67,33 @@ public class CDOM implements IASTServiceProvider {
     }
     
 
+    /**
+     * Constant <code>PARSE_SAVED_RESOURCES</code> - Parse saved resources in the workspace
+     */
     public static final int PARSE_SAVED_RESOURCES = 0; 
+    /**
+     * Constant <code>PARSE_WORKING_COPY_WITH_SAVED_INCLUSIONS</code> - Parse working copy for
+     * translation unit, saved resources for all header files.  
+     */
     public static final int PARSE_WORKING_COPY_WITH_SAVED_INCLUSIONS = 1;
+    /**
+     * Constant <code>PARSE_WORKING_COPY_WHENEVER_POSSIBLE</code> - Parse working copy whenever possible for both
+     * header files and the file in question as a translation unit.
+     */
     public static final int PARSE_WORKING_COPY_WHENEVER_POSSIBLE = 2;
+    
+    
+    /**
+     * <code>provider</code> is registered by the UI as a IWorkingCopyProvider.
+     */
     private IWorkingCopyProvider provider;
     
+    /**
+     * This is the factory function that returns an ICodeReaderFactory instance based upon the key provided.
+     * 
+     * @param key  one of PARSE_SAVED_RESOURCES, PARSE_WORKING_COPY_WITH_SAVED_INCLUSIONS, PARSE_WORKING_COPY_WHENEVER_POSSIBLE
+     * @return     an implementation that works according to the key specified or null for an invalid key
+     */
     public ICodeReaderFactory getCodeReaderFactory( int key )
     {
         //TODO - eventually these factories will need to hook into the 
@@ -75,6 +114,8 @@ public class CDOM implements IASTServiceProvider {
      * @see org.eclipse.cdt.core.dom.IASTServiceProvider#getTranslationUnit(org.eclipse.core.resources.IFile)
      */
     public IASTTranslationUnit getTranslationUnit(IFile fileToParse) throws UnsupportedDialectException {
+    	//TODO - At this time, we purely delegate blindly
+    	//In the future, we may need to delegate based upon context provided 
         return defaultService.getTranslationUnit(fileToParse);
     }
 
@@ -82,13 +123,17 @@ public class CDOM implements IASTServiceProvider {
      * @see org.eclipse.cdt.core.dom.IASTServiceProvider#getTranslationUnit(org.eclipse.core.resources.IFile, org.eclipse.cdt.core.dom.ICodeReaderFactory)
      */
     public IASTTranslationUnit getTranslationUnit(IFile fileToParse, ICodeReaderFactory fileCreator) throws UnsupportedDialectException {
-        return defaultService.getTranslationUnit(fileToParse, fileCreator );
+    	//TODO - At this time, we purely delegate blindly
+    	//In the future, we may need to delegate based upon context provided 
+    	return defaultService.getTranslationUnit(fileToParse, fileCreator );
     }
 
     /* (non-Javadoc)
      * @see org.eclipse.cdt.core.dom.IASTServiceProvider#getTranslationUnit(org.eclipse.core.resources.IFile, org.eclipse.cdt.core.dom.ICodeReaderFactory, org.eclipse.cdt.core.dom.IParserConfiguration)
      */
     public IASTTranslationUnit getTranslationUnit(IFile fileToParse, ICodeReaderFactory fileCreator, IParserConfiguration configuration) throws UnsupportedDialectException {
+    	//TODO - At this time, we purely delegate blindly
+    	//In the future, we may need to delegate based upon context provided     	
         return defaultService.getTranslationUnit(fileToParse, fileCreator, configuration );
     }
     
@@ -97,11 +142,15 @@ public class CDOM implements IASTServiceProvider {
 	 */
 	public ASTCompletionNode getCompletionNode(IFile fileToParse, int offset,
 			ICodeReaderFactory fileCreator) throws UnsupportedDialectException {
+    	//TODO - At this time, we purely delegate blindly
+    	//In the future, we may need to delegate based upon context provided 
 		return defaultService.getCompletionNode(fileToParse, offset, fileCreator);
 	}
 
     /**
-     * @param workingCopyProvider
+     * This method allows a UI component to register its IWorkingCopyProvider to the CDOM.
+     * 
+     * @param workingCopyProvider - UI components buffer manager
      */
     public void setWorkingCopyProvider(IWorkingCopyProvider workingCopyProvider) {
         this.provider = workingCopyProvider;

core/org.eclipse.cdt.core/src/org/eclipse/cdt/core/dom/IASTServiceProvider.java

@@ -15,20 +15,64 @@ import org.eclipse.cdt.core.dom.ast.IASTTranslationUnit;
 import org.eclipse.core.resources.IFile;
 
 /**
+ * This is the mechanism that represents a parser service in the CDT.
+ * 
+ * IASTTranslationUnits and ASTCompletionNodes are artifacts that this service returns.
+ * 
  * @author jcamelon
  */
 public interface IASTServiceProvider {
     
+    /**
+     * This exception is thrown when there is not a service provider that can handle
+     * the request due to dialect mis-match.  
+     * 
+     * @author jcamelon
+     */
     public static class UnsupportedDialectException extends Exception 
     {
+    	
     }
 
+    /**
+     * Returns a parse tree that represents the content provided as parameters.
+     * 
+     * @param fileToParse the file in question	
+     * @return syntactical parse tree
+     * @throws UnsupportedDialectException 
+     */
     public IASTTranslationUnit getTranslationUnit( IFile fileToParse) throws UnsupportedDialectException;
     
+    /**
+     * Returns a parse tree that represents the content provided as parameters.
+     * 
+     * @param fileToParse the file in question
+     * @param fileCreator @see CDOM#getCodeReaderFactory(int)
+     * @return syntactical parse tree
+     * @throws UnsupportedDialectException
+     */
     public IASTTranslationUnit getTranslationUnit( IFile fileToParse, ICodeReaderFactory fileCreator  )throws UnsupportedDialectException;
 
+    /**
+     * Returns a parse tree that represents the content provided as parameters.
+     * 
+     * @param fileToParse the file in question
+     * @param fileCreator @see CDOM#getCodeReaderFactory(int)
+     * @param configuration parser configuration provided rather than discovered by service
+     * @return syntactical parse tree
+     * @throws UnsupportedDialectException
+     */
     public IASTTranslationUnit getTranslationUnit( IFile fileToParse, ICodeReaderFactory fileCreator, IParserConfiguration configuration )throws UnsupportedDialectException;
 
+    /**
+     * Returns a parse tree that represents the content provided as parameters.
+     * 
+     * @param fileToParse the file in question
+     * @param offset the offset at which you require completion at
+     * @param fileCreator @see CDOM#getCodeReaderFactory(int)
+     * @return syntactical parse tree
+     * @throws UnsupportedDialectException
+     */
     public ASTCompletionNode getCompletionNode( IFile fileToParse, int offset, ICodeReaderFactory fileCreator) throws UnsupportedDialectException;
     
 }