Comment adjustment.

core/org.eclipse.cdt.core/model/org/eclipse/cdt/core/settings/model/ICConfigurationDescription.java

@@ -6,7 +6,7 @@
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
- * Intel Corporation - Initial API and implementation
+ *     Intel Corporation - Initial API and implementation
  *******************************************************************************/
 package org.eclipse.cdt.core.settings.model;
 
@@ -21,62 +21,63 @@ import org.eclipse.core.runtime.IPath;
 import org.eclipse.core.runtime.QualifiedName;
 
 /**
- * this is the element representing configuration and thus this is the root element
+ * This is the element representing configuration and thus this is the root element
- * for configuration-specific settings   
+ * for configuration-specific settings
- *
  */
-public interface ICConfigurationDescription extends ICSettingContainer, ICSettingObject, ICSettingsStorage{
+public interface ICConfigurationDescription extends ICSettingContainer, ICSettingObject, ICSettingsStorage {
 	/**
 	 * Returns whether or not this is an active configuration.
-	 * Active configuratiuon is the one that is built by default.
+	 * Active configuration is the one that is built by default.
-	 * This configuration is returned by the {@link ICProjectDescription#getActiveConfiguration()} call
+	 * This configuration is returned by the {@link ICProjectDescription#getActiveConfiguration()}
-	 * 
+	 * call
+	 *
 	 * @return boolean
 	 */
 	boolean isActive();
 
 	/**
-	 * returns the human-readable configuration description
+	 * Returns the human-readable configuration description.
 	 */
 	String getDescription();
-	
+
 	/**
-	 * sets the configuration description
+	 * Sets the configuration description
-	 * 
+	 *
 	 * @param des
 	 * @throws WriteAccessException when the configuration description is read-only
 	 * see {@link CoreModel#getProjectDescription(org.eclipse.core.resources.IProject, boolean)}
 	 */
 	void setDescription(String des) throws WriteAccessException;
-	
+
 	/**
-	 * returns the project description this configuration belongs to
+	 * Returns the project description this configuration belongs to
 	 */
 	ICProjectDescription getProjectDescription();
-	
+
 	/**
-	 * returns the "root" folder description
+	 * Returns the "root" folder description
 	 * The root folder description is the default one used for the project root folder
 	 * The root folder description can not be null
 	 */
 	ICFolderDescription getRootFolderDescription();
-	
+
 	/**
-	 * returns the complete set of folder descriptions defined for this configuration
+	 * Returns the complete set of folder descriptions defined for this configuration
 	 * The folder description is the settings holder for the specified folder
 	 * @see ICFolderDescription
 	 */
 	ICFolderDescription[] getFolderDescriptions();
 
 	/**
-	 * returns the complete set of file descriptions defined for this configuration
+	 * Returns the complete set of file descriptions defined for this configuration
 	 * The file description is the settings holder for the specified file
 	 * @see ICFileDescription
 	 */
 	ICFileDescription[] getFileDescriptions();
 
 	/**
-	 * returns the complete set of file and folder descriptions (resource descriptions) defined for this configuration
+	 * Returns the complete set of file and folder descriptions (resource descriptions) defined
+	 * for this configuration
 	 * The resource description is the settings holder for the specified resource
 	 * @see ICResourceDescription
 	 * @see ICFileDescription
@@ -86,111 +87,117 @@ public interface ICConfigurationDescription extends ICSettingContainer, ICSettin
 
 	/**
 	 * Returns the resource description for the given path
-	 * 
+	 *
 	 * @param path - project-relative workspace resource path
-	 * @param exactPath - when true the resource description of the given path is searched and if not found null is returned,
+	 * @param exactPath - when true the resource description of the given path is searched and if
+	 * 		not found null is returned,
 	 * if false, the resource description applicable for the given path is returned,
 	 * i.e. if the configuration contains resource descriptions of the following paths "" and "a/"
 	 * getResourceDescription(new Path("a/b"), true) returns null
 	 * getResourceDescription(new Path("a/b"), false) returns the "a" folder description
-	 * @return {@link ICResourceDescription} that is either a {@link ICFolderDescription} or an {@link ICFileDescription}
+	 * @return {@link ICResourceDescription} that is either a {@link ICFolderDescription} or
+	 * 		an {@link ICFileDescription}
 	 */
 	ICResourceDescription getResourceDescription(IPath path, boolean exactPath);
 
 	/**
-	 * removes the given resource description from the configuration
+	 * Removes the given resource description from the configuration
-	 * 
+	 *
 	 * @param des
 	 * @throws CoreException
 	 * @throws WriteAccessException when the configuration description is read-only
 	 * see {@link CoreModel#getProjectDescription(org.eclipse.core.resources.IProject, boolean)}
 	 */
 	void removeResourceDescription(ICResourceDescription des) throws CoreException, WriteAccessException;
-	
+
 	/**
-	 * creates a new file description for the specified path
+	 * Creates a new file description for the specified path
 	 * @param path project-relative file workspace path
-	 * @param base resource description from which settings will be coppied/inheritted 
+	 * @param base resource description from which settings will be coppied/inheritted
 	 * @throws CoreException
 	 * @throws WriteAccessException when the configuration description is read-only
 	 * see {@link CoreModel#getProjectDescription(org.eclipse.core.resources.IProject, boolean)}
 	 */
 	ICFileDescription createFileDescription(IPath path, ICResourceDescription base) throws CoreException, WriteAccessException;
-	
+
 	/**
-	 * creates a new folder description for the specified path
+	 * Creates a new folder description for the specified path
 	 * @param path project-relative folder workspace path
-	 * @param base resource description from which settings will be coppied/inheritted 
+	 * @param base resource description from which settings will be coppied/inheritted
 	 * @throws CoreException
 	 * @throws WriteAccessException when the configuration description is read-only
 	 * see {@link CoreModel#getProjectDescription(org.eclipse.core.resources.IProject, boolean)}
 	 */
 	ICFolderDescription createFolderDescription(IPath path, ICFolderDescription base) throws CoreException, WriteAccessException;
-	
+
 	/**
-	 * returns the ID of the build system used with this configuration
+	 * Returns the ID of the build system used with this configuration
-	 * i.e. the id of extension contributing to the org.eclipse.cdt.core.CConfigurationDataProvider extension point
+	 * i.e. the id of extension contributing to the org.eclipse.cdt.core.CConfigurationDataProvider
-	 * used with this configuration
+	 * extension point used with this configuration
-	 *  
+	 *
 	 * @return String
 	 */
 	String getBuildSystemId();
-	
+
 	/**
-	 * This method should be used by the build system only for gettings
+	 * This method should be used by the build system only for getting
 	 * the build-system contributed CConfigurationData
-	 * @see CConfigurationDataProvider and the org.eclipse.cdt.core.CConfigurationDataProvider extension point
+	 * @see CConfigurationDataProvider and the org.eclipse.cdt.core.CConfigurationDataProvider
+	 * extension point
 	 */
 	CConfigurationData getConfigurationData();
-	
+
 	/**
-	 * sets this cinfiguration as active
+	 * Sets this configuration as active
-	 * this call is equivalent to {@link ICProjectDescription#setActiveConfiguration(ICConfigurationDescription)}
+	 * this call is equivalent to
-	 * Active configuratiuon is the one that is built by default.
+	 * {@link ICProjectDescription#setActiveConfiguration(ICConfigurationDescription)}
-	 * This configuration is returned by the {@link ICProjectDescription#getActiveConfiguration()} call
+	 * Active configuration is the one that is built by default.
-	 * 
+	 * This configuration is returned by the {@link ICProjectDescription#getActiveConfiguration()}
+	 * call
+	 *
 	 * @throws WriteAccessException when the configuration description is read-only,
 	 * see {@link CoreModel#getProjectDescription(org.eclipse.core.resources.IProject, boolean)}
 	 */
 	void setActive() throws WriteAccessException;
-	
+
 	/**
 	 * This method should be used by the build system only for updating
 	 * the build-system contributed CConfigurationData
-	 * 
+	 *
 	 * @throws WriteAccessException when the configuration description is read-only,
 	 * see {@link CoreModel#getProjectDescription(org.eclipse.core.resources.IProject, boolean)}
-	 * 
+	 *
-	 * @see CConfigurationDataProvider and the extension point org.eclipse.cdt.core.CConfigurationDataProvider
+	 * @see CConfigurationDataProvider and the extension point
+	 * 		org.eclipse.cdt.core.CConfigurationDataProvider
 	 */
 	void setConfigurationData(String buildSystemId, CConfigurationData data) throws WriteAccessException;
-	
+
 	/**
-	 * returns whether or not the configuration description was modified
+	 * Returns whether or not the configuration description was modified
 	 */
 	boolean isModified();
-	
+
 	/**
-	 * returns the target platform settings for this configuration
+	 * Returns the target platform settings for this configuration
 	 * @see ICTargetPlatformSetting
 	 */
 	ICTargetPlatformSetting getTargetPlatformSetting();
-	
+
 	/**
-	 * returns the source entries for this configuration
+	 * Returns the source entries for this configuration
 	 * @see ICSourceEntry
 	 */
 	ICSourceEntry[] getSourceEntries();
-	
+
 	ICSourceEntry[] getResolvedSourceEntries();
 
 	/**
-	 * sets the source entries for this configuration
+	 * Sets the source entries for this configuration
-	 * 
+	 *
 	 * @param entries
-	 * 
+	 *
 	 * @throws WriteAccessException when the configuration description is read-only,
-	 * see {@link CoreModel#getProjectDescription(org.eclipse.core.resources.IProject, boolean)} 
+	 * see {@link CoreModel#getProjectDescription(org.eclipse.core.resources.IProject, boolean)}
 	 */
 	void setSourceEntries(ICSourceEntry[] entries) throws CoreException, WriteAccessException;
 
@@ -198,9 +205,9 @@ public interface ICConfigurationDescription extends ICSettingContainer, ICSettin
 	 * Returns a Map of configurations referenced by this configuration. Settings exported
 	 * by a project configuration are automatically picked up by any referencing configurations.
 	 * <p>
-	 * This Map is keyed by project name with value equal to the referenced configuration's ID, or the
+	 * This Map is keyed by project name with value equal to the referenced configuration's ID, or
-	 * empty string. The empty string is a special configuration value which indicates the reference
+	 * the empty string. The empty string is a special configuration value which indicates
-	 * tracks the Active configuration in the referenced Project.
+	 * the reference tracks the Active configuration in the referenced Project.
 	 * <p>
 	 * If the current configuration does not reference any other configurations,
 	 * an empty map is returned.
@@ -231,7 +238,7 @@ public interface ICConfigurationDescription extends ICSettingContainer, ICSettin
 	void setReferenceInfo(Map<String, String> refs) throws WriteAccessException;
 
 	/**
-	 * returns an array of settings exported by this configuration
+	 * Returns an array of settings exported by this configuration
 	 * in case some configurations refer (depend on) this configuration
 	 * exported settings of this configuration get applied to those configurations
 	 * @see ICExternalSetting
@@ -239,16 +246,16 @@ public interface ICConfigurationDescription extends ICSettingContainer, ICSettin
 	 * @see #setReferenceInfo(Map)
 	 */
 	ICExternalSetting[] getExternalSettings();
-	
+
 	/**
-	 * creates/adds external setting to this configuration 
+	 * Creates/adds external setting to this configuration
 	 * in case some configurations refer (depend on) this configuration
 	 * exported settings of this configuration get applied to those configurations
 	 * @see ICExternalSetting
 	 * @see #getReferenceInfo()
 	 * @see #setReferenceInfo(Map)
-	 * @see #getExternalSettings() 
+	 * @see #getExternalSettings()
-	 * 
+	 *
 	 * @param languageIDs
 	 * @param contentTypeIds
 	 * @param extensions
@@ -262,14 +269,14 @@ public interface ICConfigurationDescription extends ICSettingContainer, ICSettin
 			ICSettingEntry entries[]) throws WriteAccessException;
 
 	/**
-	 * removes external setting from this configuration 
+	 * Removes external setting from this configuration
 	 * in case some configurations refer (depend on) this configuration
 	 * exported settings of this configuration get applied to those configurations
 	 * @see ICExternalSetting
 	 * @see #getReferenceInfo()
 	 * @see #setReferenceInfo(Map)
-	 * @see #getExternalSettings() 
+	 * @see #getExternalSettings()
-	 * 
+	 *
 	 * @param setting
 	 * @throws WriteAccessException when the configuration description is read-only
 	 * see {@link CoreModel#getProjectDescription(org.eclipse.core.resources.IProject, boolean)}
@@ -277,104 +284,106 @@ public interface ICConfigurationDescription extends ICSettingContainer, ICSettin
 	void removeExternalSetting(ICExternalSetting setting) throws WriteAccessException;
 
 	/**
-	 * removes all external settings from this configuration 
+	 * Removes all external settings from this configuration
 	 * in case some configurations refer (depend on) this configuration
 	 * exported settings of this configuration get applied to those configurations
 	 * @see ICExternalSetting
 	 * @see #getReferenceInfo()
 	 * @see #setReferenceInfo(Map)
-	 * @see #getExternalSettings() 
+	 * @see #getExternalSettings()
-	 * 
+	 *
 	 * @throws WriteAccessException when the configuration description is read-only
 	 * see {@link CoreModel#getProjectDescription(org.eclipse.core.resources.IProject, boolean)}
 	 */
 	void removeExternalSettings() throws WriteAccessException;
-	
+
 	/**
-	 * returns the build setting for this configuration
+	 * Returns the build setting for this configuration
 	 * @see ICBuildSetting
 	 */
 	ICBuildSetting getBuildSetting();
-	
+
 	/**
-	 * returns the CDT variable contributor that represent information on the
+	 * Returns the CDT variable contributor that represent information on the
-	 * CDT variables (Build Macros) contributed/used with this configuration 
+	 * CDT variables (Build Macros) contributed/used with this configuration
-	 * 
+	 *
 	 * @see ICdtVariablesContributor
 	 */
 	ICdtVariablesContributor getBuildVariablesContributor();
-	
+
 	/**
-	 * the get/setSettionsProperty methods allow to associate the session properties mechanism on the configuration level
+	 * The get/setSettionsProperty methods allow to associate the session properties mechanism on
-	 * session properties are not persisted and are not restored on the next eclipse session
+	 * the configuration level session properties are not persisted and are not restored on the next
-	 * the scope of configuration session properties is the current configuration description,
+	 * eclipse session the scope of configuration session properties is the current configuration
-	 * i.e. modifications to the properties are not applied until the setProjectDescription call
+	 * description, i.e. modifications to the properties are not applied until
+	 * the setProjectDescription call
 	 */
 	Object getSessionProperty(QualifiedName name);
 
 	/**
-	 * the get/setSettionsProperty methods allow to associate the session properties mechanism on the configuration level
+	 * The get/setSettionsProperty methods allow to associate the session properties mechanism on
-	 * session properties are not persisted and are not restored on the next eclipse session
+	 * the configuration level session properties are not persisted and are not restored on the next
-	 * the scope of configuration session properties is the current configuration description,
+	 * eclipse session the scope of configuration session properties is the current configuration
-	 * i.e. modifications to the properties are not applied until the setProjectDescription call
+	 * description, i.e. modifications to the properties are not applied until
-	 * 
+	 * the setProjectDescription call
+	 *
 	 * @param name
 	 * @param value
 	 */
 	void setSessionProperty(QualifiedName name, Object value);
-	
+
 	/**
-	 * sets the name for this configuration
+	 * Sets the name for this configuration
-	 * 
+	 *
 	 * @param name
 	 * @throws WriteAccessException when the configuration description is read-only
 	 * see {@link CoreModel#getProjectDescription(org.eclipse.core.resources.IProject, boolean)}
 	 */
 	void setName(String name) throws WriteAccessException;
-	
+
 	ICConfigExtensionReference[] get(String extensionPointID);
-	
+
 	ICConfigExtensionReference create(String extensionPoint, String extension) throws CoreException;
-	
+
 	void remove(ICConfigExtensionReference ext) throws CoreException;
-	
+
 	void remove(String extensionPoint) throws CoreException;
-	
+
 	boolean isPreferenceConfiguration();
-	
+
 	/**
-	 * convenience method to return a language setting for the file
+	 * Convenience method to return a language setting for the file
 	 * with the specified project-relative path
-	 * 
+	 *
 	 * @param path - file project relative path
 	 * @return ICLanguageSetting or null if not found
 	 */
 	ICLanguageSetting getLanguageSettingForFile(IPath path, boolean ignoreExludeStatus);
-	
+
 	/**
-	 * sets the external setting providers to be used for the configuration
+	 * Sets the external setting providers to be used for the configuration
-	 * 
+	 *
 	 * @param ids the ids of externalSettinsProvider extensions
 	 */
 	void setExternalSettingsProviderIds(String ids[]);
 
 	/**
-	 * returns the ids of external setting providers used for the configuration
+	 * Returns the ids of external setting providers used for the configuration
-	 * 
+	 *
 	 * @return the ids of externalSettinsProvider extensions
 	 */
 	String[] getExternalSettingsProviderIds();
-	
+
 	/**
-	 * tells the configuration to update the given providers
+	 * Tells the configuration to update the given providers
 	 * In case the specified ids contain provider ids not associated with the configuration,
 	 * those ids will be ignored and will NOT be added to the configuration settings
-	 * 
+	 *
 	 * @param ids the ids of externalSettinsProvider extensions
-	 * 
+	 *
 	 * @see ICProjectDescriptionManager#updateExternalSettingsProviders(String[], org.eclipse.core.runtime.IProgressMonitor)
 	 */
 	void updateExternalSettingsProviders(String[] ids) throws WriteAccessException;
-	
+
 	CConfigurationStatus getConfigurationStatus();
 }