API cleanup & JavaDoc

core/org.eclipse.cdt.core/model/org/eclipse/cdt/core/language/settings/providers/ICListenerAgent.java

@@ -15,10 +15,27 @@ import org.eclipse.cdt.core.settings.model.ICConfigurationDescription;
 
 
 /**
- * Helper class to allow listeners self-register/dispose. Called by cdt core.
- * TODO - expand in more detail.
+ * Helper class to allow listeners of arbitrary events self-register/dispose.
+ *
+ * Called by CDT core when {@linkplain ICListenerAgent} added/removed to
+ * the list of {@link ILanguageSettingsProvider}s  managed by the model.
+ * {@linkplain ICListenerAgent} would commonly be implemented by a language
+ * settings provider.
+ * <br><br>
+ * Implementers are to create a specific listener and register it to
+ * appropriate event manager in {@link #registerListener(ICConfigurationDescription)}
+ * then unregister and dispose in {@link #unregisterListener()}.
  */
 public interface ICListenerAgent {
+	/**
+	 * Registers a specific listener.
+	 *
+	 * @param cfgDescription - configuration description for the listener.
+	 */
 	public void registerListener(ICConfigurationDescription cfgDescription);
+
+	/**
+	 * Unregister listener and dispose all resources.
+	 */
 	public void unregisterListener();
 }

core/org.eclipse.cdt.core/model/org/eclipse/cdt/core/language/settings/providers/ILanguageSettingsProvider.java

@@ -1,12 +1,12 @@
 /*******************************************************************************
- * Copyright (c) 2009, 2010 Andrew Gvozdev (Quoin Inc.) and others.
+ * Copyright (c) 2009, 2011 Andrew Gvozdev 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
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
- *     Andrew Gvozdev (Quoin Inc.) - initial API and implementation
+ *     Andrew Gvozdev - initial API and implementation
  *******************************************************************************/
 
 package org.eclipse.cdt.core.language.settings.providers;
@@ -20,32 +20,32 @@ import org.eclipse.cdt.core.settings.model.ICSettingEntry;
 import org.eclipse.core.resources.IResource;
 
 /**
- * Base interface to provide list of {@link ICLanguageSettingEntry}. 
- * This interface is used to deliver additions to compiler options such as 
+ * Base interface to provide list of {@link ICLanguageSettingEntry}.
+ * This interface is used to deliver additions to compiler options such as
  * include paths (-I) or preprocessor defines (-D) and others (see
  * {@link ICSettingEntry#INCLUDE_PATH} and other kinds).
- * 
+ * <br>
  * To define a provider like that use extension point
  * {@code org.eclipse.cdt.core.LanguageSettingsProvider} and implement this
  * interface. CDT provides a few general use implementations such as
- * {@link LanguageSettingsBaseProvider} which could be used out of the box or
- * extended. See extension point schema description LanguageSettingsProvider.exsd
- * for more details.
- * 
+ * {@link LanguageSettingsBaseProvider} or {@link LanguageSettingsSerializable}
+ * which could be used out of the box or extended. See also extension point
+ * schema description LanguageSettingsProvider.exsd.
+ *
  * @since 6.0
  */
 public interface ILanguageSettingsProvider {
 	/**
 	 * Id is used to keep track of the providers internally. Use unique id
 	 * to represent the provider.
-	 * 
+	 *
 	 * @return Id of the provider.
 	 */
 	public String getId();
 
 	/**
 	 * Name is used to present the provider to the end user in UI.
-	 * 
+	 *
 	 * @return name of the provider.
 	 */
 	public String getName();
@@ -53,12 +53,21 @@ public interface ILanguageSettingsProvider {
 	/**
 	 * Returns the list of setting entries for the given configuration description,
 	 * resource and language.
-	 * 
+	 * <br><br>
+	 * Note to implementers - this method should not be used to do any long running
+	 * operations such as extensive calculations or reading files. If you need to do
+	 * so, the recommended way is to do the calculations outside of
+	 * this function call - in advance and on appropriate event. For example, Build
+	 * Output Parser prepares the list and stores it in internal cache while parsing output.
+	 * {@link #getSettingEntries(ICConfigurationDescription, IResource, String)} will
+	 * return cached entries when asked. You can also implement {@link ICListenerAgent}
+	 * interface to get registered and listen to arbitrary events.
+	 *
 	 * @param cfgDescription - configuration description.
 	 * @param rc - resource such as file or folder.
 	 * @param languageId - language id
 	 *     (see {@link LanguageManager#getLanguageForFile(org.eclipse.core.resources.IFile, ICConfigurationDescription)}).
-	 * 
+	 *
 	 * @return the list of setting entries or {@code null} if no settings defined.
 	 */
 	public List<ICLanguageSettingEntry> getSettingEntries(ICConfigurationDescription cfgDescription, IResource rc, String languageId);

core/org.eclipse.cdt.core/model/org/eclipse/cdt/internal/core/language/settings/providers/LanguageSettingsProvidersSerializer.java

@@ -83,8 +83,8 @@ public class LanguageSettingsProvidersSerializer {
 		private ICListenerAgent listener;
 		private ICConfigurationDescription cfgDescription;
 
-		public ListenerAssociation(ICListenerAgent li, ICConfigurationDescription cfgd) {
-			listener = li;
+		public ListenerAssociation(ICListenerAgent la, ICConfigurationDescription cfgd) {
+			listener = la;
 			cfgDescription = cfgd;
 		}
 	}
@@ -864,7 +864,7 @@ projects:
 	}
 
 	/**
-	 * Get a providers list including only providers of type ICListenerRegisterer
+	 * Get a providers list including only providers of type {@link ICListenerAgent}
 	 * for a given project description - collecting from all configurations.
 	 */
 	private static List<ICListenerAgent> getListeners(ICProjectDescription prjDescription) {
@@ -895,7 +895,7 @@ projects:
 	}
 
 	/**
-	 * Get a providers list including only providers of type IResourceChangeListener
+	 * Get a providers list including only providers of type {@link ICListenerAgent}
 	 * for a given project description - collecting from all configurations.
 	 */
 	private static List<ListenerAssociation> getListenersAssociations(ICProjectDescription prjDescription) {
@@ -916,7 +916,8 @@ projects:
 
 	/**
 	 * Unregister listeners which are not used anymore and register new listeners.
-	 * The method is used when project description is applied to workspace.
+	 * The method is called when project description is applied to workspace.
+	 *
 	 * @param oldPrjDescription - old project descriptions being replaced in the workspace.
 	 * @param newPrjDescription - new project description being applied to the workspace.
 	 */

core/org.eclipse.cdt.core/schema/LanguageSettingsProvider.exsd

@@ -15,6 +15,9 @@
          <appInfo>
             <meta.element />
          </appInfo>
+         <documentation>
+            This extension point is used to contribute a new Language Settings Provider. A Language Settings Provider is used to get additions to compiler options such as include paths (-I) or preprocessor defines (-D) and others into the project model.
+         </documentation>
       </annotation>
       <complexType>
          <sequence minOccurs="1" maxOccurs="unbounded">