JavaDoc mostly

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

@@ -35,9 +35,10 @@ public interface ILanguageSettingsEditableProvider extends ILanguageSettingsBroa
 	 * Sets language settings entries for the provider.
 	 *
 	 * @param cfgDescription - configuration description.
-	 * @param rc - resource such as file or folder.
+	 * @param rc - resource such as file or folder. If {@code null} the entries are
-	 * @param languageId - language id. If {@code null}, then entries are considered to be defined for
+	 *    considered to be being defined as default entries for resources.
-	 *    any language.
+	 * @param languageId - language id. If {@code null}, then entries are considered
+	 *    to be defined as default entries for languages.
 	 * @param entries - language settings entries to set.
 	 */
 	public void setSettingEntries(ICConfigurationDescription cfgDescription, IResource rc, String languageId, List<ICLanguageSettingEntry> entries);

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

@@ -27,12 +27,18 @@ import org.eclipse.core.resources.IResource;
  * <br><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
+ * interface. The recommended way of implementing is to extend
- * {@link LanguageSettingsBaseProvider} or {@link LanguageSettingsSerializableProvider}
+ * {@link LanguageSettingsSerializableProvider} and implement {@link ILanguageSettingsEditableProvider}.
- * or {@link LanguageSettingsGenericProvider} which could be used out of the box or
+ * That will give the ability to persist and edit/clean entries by user in UI.
- * extended. See also extension point schema description LanguageSettingsProvider.exsd.
+ * The clone methods defined by {@link ILanguageSettingsEditableProvider} should be
- *
+ * chained as done for example by {@link LanguageSettingsGenericProvider}.
- * @since 6.0
+ * <br><br>
+ * CDT provides a few general use implementations in the core such as {@link LanguageSettingsBaseProvider}
+ * or {@link LanguageSettingsSerializableProvider} or {@link LanguageSettingsGenericProvider}
+ * which could be used out of the box or built upon. There are also abstract classes in build
+ * plugins {@code AbstractBuildCommandParser} and {@code AbstractBuiltinSpecsDetector} which
+ * serve as a base for output parsers and built-in compiler language settings detectors.
+ * See also extension point schema description LanguageSettingsProvider.exsd.
  */
 public interface ILanguageSettingsProvider {
 	/**
@@ -65,7 +71,9 @@ public interface ILanguageSettingsProvider {
 	 *
 	 * @param cfgDescription - configuration description.
 	 * @param rc - resource such as file or folder.
-	 * @param languageId - language id
+	 *    If {@code null}, the default entries for all resources are returned.
+	 * @param languageId - language id.
+	 *    If {@code null}, the default entries for all languages are returned.
 	 *     (see {@link LanguageManager#getLanguageForFile(org.eclipse.core.resources.IFile, ICConfigurationDescription)}).
 	 *
 	 * @return the list of setting entries or {@code null} if no settings defined.

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

@@ -8,12 +8,14 @@
  * Contributors:
  *     Andrew Gvozdev - initial API and implementation
  *******************************************************************************/
-
 package org.eclipse.cdt.core.language.settings.providers;
 
 /**
  * Generic implementation of language settings provider which can be edited in UI
  * with entries persisted between eclipse sessions.
+ * The instances of this class can be used in plugin.xml to create a new provider
+ * but this class is not intended to be extended. For more details how to create a
+ * language settings provider see the description of {@link ILanguageSettingsProvider}.
  */
 final public class LanguageSettingsGenericProvider extends LanguageSettingsSerializableProvider
 		implements ILanguageSettingsEditableProvider {

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

@@ -8,7 +8,6 @@
  * Contributors:
  *     Andrew Gvozdev - initial API and implementation
  *******************************************************************************/
-
 package org.eclipse.cdt.core.language.settings.providers;
 
 import java.util.ArrayList;
@@ -17,24 +16,25 @@ import java.util.List;
 import org.eclipse.cdt.core.CCorePlugin;
 import org.eclipse.cdt.core.settings.model.ICConfigurationDescription;
 import org.eclipse.cdt.core.settings.model.ICLanguageSettingEntry;
+import org.eclipse.cdt.core.settings.model.ICProjectDescription;
 import org.eclipse.cdt.internal.core.XmlUtil;
+import org.eclipse.cdt.internal.core.language.settings.providers.LanguageSettingsProvidersSerializer;
 import org.eclipse.cdt.internal.core.language.settings.providers.LanguageSettingsSerializableStorage;
 import org.eclipse.core.resources.IResource;
 import org.w3c.dom.Element;
 import org.w3c.dom.Node;
 import org.w3c.dom.NodeList;
 
-
 /**
  * This class is the base class for language settings providers able to serialize
  * into XML storage.
- * Although this class has setter methods, it is not editable in UI by design.
+ * Although this class has setter methods, its instances are not editable in UI by
- * Implement {@link ILanguageSettingsEditableProvider} interface for that.
+ * design. Implement {@link ILanguageSettingsEditableProvider} interface for that.
- *
+ * For more on the suggested way of extending this class see the description of
- * TODO - more JavaDoc, info and hints about class hierarchy
+ * {@link ILanguageSettingsProvider}.
- *
  */
 public class LanguageSettingsSerializableProvider extends LanguageSettingsBaseProvider implements ILanguageSettingsBroadcastingProvider {
+	/** This field is for internal use only */
 	public static final String ELEM_PROVIDER = "provider"; //$NON-NLS-1$
 	private static final String ATTR_ID = "id"; //$NON-NLS-1$
 
@@ -53,6 +53,7 @@ public class LanguageSettingsSerializableProvider extends LanguageSettingsBasePr
 
 	/**
 	 * Default constructor. This constructor has to be always followed with setting id and name of the provider.
+	 * This constructor is necessary to instantiate the class via the extension point in plugin.xml.
 	 */
 	public LanguageSettingsSerializableProvider() {
 		super();
@@ -62,7 +63,7 @@ public class LanguageSettingsSerializableProvider extends LanguageSettingsBasePr
 	 * Constructor.
 	 *
 	 * @param id - id of the provider.
-	 * @param name - name of the provider. Note that this name may show up in UI.
+	 * @param name - name of the provider. Note that this name shows up in UI.
 	 */
 	public LanguageSettingsSerializableProvider(String id, String name) {
 		super(id, name);
@@ -153,12 +154,19 @@ public class LanguageSettingsSerializableProvider extends LanguageSettingsBasePr
 
 	/**
 	 * Sets language settings entries for the provider.
-	 * Note that the entries are not persisted at that point. To persist use TODO
+	 * Note that the entries are not persisted at that point. Use this method to
+	 * set the entries for all resources and then to persist use
+	 * {@fixme FIXME - update references with API versions}
+	 * {@link LanguageSettingsProvidersSerializer#serializeLanguageSettings(ICProjectDescription)} or
+	 * {@link LanguageSettingsProvidersSerializer#serializeLanguageSettingsWorkspace()}.
+	 * See for example {@code AbstractBuildCommandParser} and {@code AbstractBuiltinSpecsDetector}
+	 * in build plugins.
 	 *
 	 * @param cfgDescription - configuration description.
-	 * @param rc - resource such as file or folder.
+	 * @param rc - resource such as file or folder. If {@code null} the entries are
-	 * @param languageId - language id. If {@code null}, then entries are considered to be defined for
+	 *    considered to be being defined as default entries for resources.
-	 *    the language scope. See {@link #getLanguageScope()}
+	 * @param languageId - language id. If {@code null}, then entries are considered
+	 *    to be defined for the language scope. See {@link #getLanguageScope()}
 	 * @param entries - language settings entries to set.
 	 */
 	public void setSettingEntries(ICConfigurationDescription cfgDescription, IResource rc, String languageId, List<ICLanguageSettingEntry> entries) {
@@ -171,17 +179,18 @@ public class LanguageSettingsSerializableProvider extends LanguageSettingsBasePr
 	 * <br>
 	 * Note that this list is <b>unmodifiable</b>. To modify the list copy it, change and use
 	 * {@link #setSettingEntries(ICConfigurationDescription, IResource, String, List)}.
-	 * <br>
+	 * <br><br>
 	 * Note also that <b>you can compare these lists with simple equality operator ==</b>,
-	 * as lists themselves are backed by WeakHashSet<List<ICLanguageSettingEntry>> where
+	 * as the lists themselves are backed by WeakHashSet<List<ICLanguageSettingEntry>> where
 	 * identical copies (deep comparison is used) are replaced with the same one instance.
 	 */
 	@Override
 	public List<ICLanguageSettingEntry> getSettingEntries(ICConfigurationDescription cfgDescription, IResource rc, String languageId) {
-		List<ICLanguageSettingEntry> entries = fStorage.getSettingEntries(cfgDescription, rc, languageId);
+		String rcProjectPath = rc!=null ? rc.getProjectRelativePath().toString() : null;
+		List<ICLanguageSettingEntry> entries = fStorage.getSettingEntries(rcProjectPath, languageId);
 		if (entries == null) {
-			if (languageId!=null && (languageScope==null || languageScope.contains(languageId))) {
+			if (languageId != null && (languageScope == null || languageScope.contains(languageId))) {
-				entries = getSettingEntries(cfgDescription, rc, null);
+				entries = fStorage.getSettingEntries(rcProjectPath, null);
 			}
 		}
 
@@ -195,7 +204,7 @@ public class LanguageSettingsSerializableProvider extends LanguageSettingsBasePr
 	 * {@link #serializeEntries(Element)} instead.
 	 *
 	 * @param parentElement - element where to serialize.
-	 * @return - newly created <provider> element. That element will already be
+	 * @return - newly created "provider" element. That element will already be
 	 *    attached to the parent element.
 	 */
 	final public Element serialize(Element parentElement) {
@@ -219,7 +228,7 @@ public class LanguageSettingsSerializableProvider extends LanguageSettingsBasePr
 	 * equivalent to serializing everything (including language scope) except entries.
 	 *
 	 * @param parentElement - element where to serialize.
-	 * @return - newly created <provider> element. That element will already be
+	 * @return - newly created "provider" element. That element will already be
 	 *    attached to the parent element.
 	 */
 	public Element serializeAttributes(Element parentElement) {
@@ -253,7 +262,7 @@ public class LanguageSettingsSerializableProvider extends LanguageSettingsBasePr
 	 * Override {@link #loadAttributes(Element)} or
 	 * {@link #loadEntries(Element)} instead.
 	 *
-	 * @param providerNode - XML element <provider> to load provider from.
+	 * @param providerNode - XML element "provider" to load provider from.
 	 */
 	final public void load(Element providerNode) {
 		fStorage.clear();
@@ -280,7 +289,7 @@ public class LanguageSettingsSerializableProvider extends LanguageSettingsBasePr
 
 	/**
 	 * Load attributes from XML provider element.
-	 * @param providerNode - XML element <provider> to load attributes from.
+	 * @param providerNode - XML element "provider" to load attributes from.
 	 */
 	public void loadAttributes(Element providerNode) {
 		String providerId = XmlUtil.determineAttributeValue(providerNode, ATTR_ID);
@@ -308,15 +317,15 @@ public class LanguageSettingsSerializableProvider extends LanguageSettingsBasePr
 
 	/**
 	 * Load provider entries from XML provider element.
-	 * @param providerNode - parent XML element <provider> where entries are defined.
+	 * @param providerNode - parent XML element "provider" where entries are defined.
 	 */
 	public void loadEntries(Element providerNode) {
 		fStorage.loadEntries(providerNode);
 	}
 
 	/**
-	 * See {@link #cloneShallow()}. This method is extracted
+	 * See {@link #cloneShallow()}. This method is extracted to avoid expressing
-	 * to avoid expressing {@link #clone()} via {@link #cloneShallow()}.
+	 * {@link #clone()} via {@link #cloneShallow()}. Do not inline to "optimize"!
 	 */
 	private LanguageSettingsSerializableProvider cloneShallowInternal() throws CloneNotSupportedException {
 		LanguageSettingsSerializableProvider clone = (LanguageSettingsSerializableProvider)super.clone();

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

@@ -19,17 +19,15 @@ import java.util.Map;
 import java.util.Map.Entry;
 import java.util.Set;
 
-import org.eclipse.cdt.core.settings.model.ICConfigurationDescription;
 import org.eclipse.cdt.core.settings.model.ICLanguageSettingEntry;
 import org.eclipse.cdt.core.settings.model.ICSettingEntry;
 import org.eclipse.cdt.internal.core.parser.util.WeakHashSet;
-import org.eclipse.core.resources.IResource;
 
+/**
+ * The class representing the (in-memory) storage for language settings entries {@link ICLanguageSettingEntry}.
+ */
 public class LanguageSettingsStorage implements Cloneable {
-	/**
+	/** Storage to keep settings entries. */
-	 * Storage to keep settings entries. Note that it is not necessary to keep configuration in the maps
-	 * as the configuration is always the one provider belongs to.
-	 */
 	protected Map<String, // languageId
 				Map<String, // resource project path
 					List<ICLanguageSettingEntry>>> fStorage = new HashMap<String, Map<String, List<ICLanguageSettingEntry>>>();
@@ -44,26 +42,28 @@ public class LanguageSettingsStorage implements Cloneable {
 		public synchronized List<ICLanguageSettingEntry> add(List<ICLanguageSettingEntry> list) {
 			return super.add(list);
 		}
-
 	};
 
 	/**
-	 * TODO
+	 * Returns the list of setting entries for the given resource and language.
 	 * <br> Note that this list is <b>unmodifiable</b>.
 	 *
+	 * @param rcProjectPath - path to the resource relative to the project.
+	 * @param languageId - language id.
+	 *
+	 * @return the list of setting entries or {@code null} if no settings defined.
 	 */
-	public List<ICLanguageSettingEntry> getSettingEntries(ICConfigurationDescription cfgDescription, IResource rc, String languageId) {
+	public List<ICLanguageSettingEntry> getSettingEntries(String rcProjectPath, String languageId) {
 		List<ICLanguageSettingEntry> entries = null;
 		Map<String, List<ICLanguageSettingEntry>> langMap = fStorage.get(languageId);
 		if (langMap!=null) {
-			String rcProjectPath = rc!=null ? rc.getProjectRelativePath().toString() : null;
 			entries = langMap.get(rcProjectPath);
 		}
 		return entries;
 	}
 
 	/**
-	 * Some providers may collect entries in pretty much random order. For the purposes of
+	 * Some providers may collect entries in pretty much random order. For the intent of
 	 * predictability, UI usability and efficient storage the entries are sorted by kinds
 	 * and secondary by name for kinds where the secondary order is not significant.
 	 *
@@ -72,7 +72,7 @@ public class LanguageSettingsStorage implements Cloneable {
 	 */
 	private List<ICLanguageSettingEntry> sortEntries(List<ICLanguageSettingEntry> entries) {
 		List<ICLanguageSettingEntry> sortedEntries = new ArrayList<ICLanguageSettingEntry>(entries);
-		Collections.sort(sortedEntries, new Comparator<ICLanguageSettingEntry>(){
+		Collections.sort(sortedEntries, new Comparator<ICLanguageSettingEntry>() {
 			/**
 			 * This comparator sorts by kinds first and the macros are sorted additionally by name.
 			 */
@@ -91,7 +91,11 @@ public class LanguageSettingsStorage implements Cloneable {
 	}
 
 	/**
+	 * Sets language settings entries for the resource and language.
 	 *
+	 * @param rcProjectPath - path to the resource relative to the project.
+	 * @param languageId - language id.
+	 * @param entries - language settings entries to set.
 	 */
 	public void setSettingEntries(String rcProjectPath, String languageId, List<ICLanguageSettingEntry> entries) {
 		synchronized (fStorage) {
@@ -104,7 +108,7 @@ public class LanguageSettingsStorage implements Cloneable {
 				List<ICLanguageSettingEntry> sortedEntries = getPooledList(sortEntries(entries), false);
 				langMap.put(rcProjectPath, sortedEntries);
 			} else {
-				// do not keep nulls in the tables
+				// reduct the empty maps in the tables
 				Map<String, List<ICLanguageSettingEntry>> langMap = fStorage.get(languageId);
 				if (langMap!=null) {
 					langMap.remove(rcProjectPath);
@@ -117,14 +121,14 @@ public class LanguageSettingsStorage implements Cloneable {
 	}
 
 	/**
-	 * @return {@code true} if the provider does not keep any settings yet or {@code false} if there are some.
+	 * @return {@code true} if the storage is empty or {@code false} otherwise.
 	 */
 	public boolean isEmpty() {
 		return fStorage.isEmpty();
 	}
 
 	/**
-	 * Clear all the entries for all configurations, all resources and all languages.
+	 * Clear all the entries for all resources and all languages.
 	 */
 	public void clear() {
 		synchronized (fStorage) {
@@ -133,7 +137,7 @@ public class LanguageSettingsStorage implements Cloneable {
 	}
 
 	/**
-	 * Returns the equal list of entries from the pool to conserve the memory.
+	 * Find and return the equal list of entries from the pool.
 	 *
 	 * @param entries - list of entries to pool.
 	 * @param copy - specify {@code true} to copy the list in order to prevent
@@ -161,7 +165,7 @@ public class LanguageSettingsStorage implements Cloneable {
 	}
 
 	/**
-	 * Returns the equal list of entries from the pool to conserve the memory.
+	 * Find and return the equal list of entries from the pool to conserve the memory.
 	 *
 	 * @param entries - list of entries to pool.
 	 * @return returns the list of entries from the pool.
@@ -171,8 +175,9 @@ public class LanguageSettingsStorage implements Cloneable {
 	}
 
 	/**
-	 * @return the empty immutable list which is pooled. Use this call rather than creating
+	 * @return Returns the empty immutable list which is pooled. Use this call rather than creating
-	 * new empty array to ensure that operator '==' can be used instead of deep equals().
+	 * new empty array to ensure that faster shallow operator '==' can be used instead of equals()
+	 * which goes deep on HashMaps.
 	 */
 	public static List<ICLanguageSettingEntry> getPooledEmptyList() {
 		List<ICLanguageSettingEntry> pooledEmptyList = Collections.emptyList();
@@ -181,7 +186,7 @@ public class LanguageSettingsStorage implements Cloneable {
 
 	/**
 	 * Clone storage for the entries. Copies references for lists of entries as a whole.
-	 * Note that is OK as the lists kept in storage are unmodifiable.
+	 * Note that that is OK as the lists kept in storage are unmodifiable and pooled.
 	 */
 	@Override
 	public LanguageSettingsStorage clone() throws CloneNotSupportedException {
@@ -197,7 +202,7 @@ public class LanguageSettingsStorage implements Cloneable {
 				for (Entry<String, List<ICLanguageSettingEntry>> entryRc : entrySetRc) {
 					String rcProjectPath = entryRc.getKey();
 					List<ICLanguageSettingEntry> lsEntries = entryRc.getValue();
-					// don't need to clone entries, they are from the LSE pool
+					// don't need to clone entries, they are from the LSE lists pool
 					mapRcClone.put(rcProjectPath, lsEntries);
 				}
 				storageClone.fStorage.put(langId, mapRcClone);

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

@@ -17,9 +17,13 @@ import org.eclipse.cdt.core.settings.model.ICLanguageSettingEntry;
  * language settings entries {@link ICLanguageSettingEntry}. The event is
  * associated with a project.
  *
- * API notes: this interface probably is not stable yet as it is not currently
+ * <p>
- * clear how it may need to be used in future. Only bare minimum is provided
+ * <strong>EXPERIMENTAL</strong>. This class interface is not stable yet as
- * here at this point.
+ * it is not currently clear how it may need to be used in future. Only bare
+ * minimum is provided here at this point (CDT 9.0).
+ * There is no guarantee that this API will work or that it will remain the same.
+ * Please do not use this API without consulting with the CDT team.
+ * </p>
  *
  * @noextend This interface is not intended to be extended by clients.
  * @noimplement This interface is not intended to be implemented by clients.

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

@@ -10,17 +10,19 @@
  *******************************************************************************/
 package org.eclipse.cdt.internal.core.language.settings.providers;
 
+import org.eclipse.cdt.core.settings.model.ICLanguageSettingEntry;
+
 /**
- * An interface for listeners to changes in language settings.
+ * An interface for listeners to changes in language settings {@link ICLanguageSettingEntry}.
- * 
+ *
  * @see LanguageSettingsProvidersSerializer#registerLanguageSettingsChangeListener(ILanguageSettingsChangeListener)
  * @see LanguageSettingsProvidersSerializer#unregisterLanguageSettingsChangeListener(ILanguageSettingsChangeListener)
  */
 public interface ILanguageSettingsChangeListener {
 	/**
 	 * Indicates that language settings have been changed.
-	 * 
+	 *
-	 * @param event - details of the event. 
+	 * @param event - details of the event.
 	 */
 	public void handleEvent(ILanguageSettingsChangeEvent event);
 }

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

@@ -13,11 +13,24 @@ package org.eclipse.cdt.internal.core.language.settings.providers;
 import java.util.LinkedHashMap;
 
 import org.eclipse.cdt.core.language.settings.providers.LanguageSettingsStorage;
+import org.eclipse.cdt.core.settings.model.ICLanguageSettingEntry;
 
 
 /**
- * This class currently is a placeholder holding old and new states.
+ * Contains the delta of changes that occurred as a result of modifying
- * If more details need to be pulled out of delta, it could be elaborated further.
+ * language settings entries {@link ICLanguageSettingEntry}. The delta is
+ * associated with a configuration description.
+ *
+ * <p>
+ * <strong>EXPERIMENTAL</strong>. This class interface is not stable yet as
+ * it is not currently clear how it may need to be used in future. Only bare
+ * minimum is provided here at this point (CDT 9.0).
+ * There is no guarantee that this API will work or that it will remain the same.
+ * Please do not use this API without consulting with the CDT team.
+ * </p>
+ *
+ * @noextend This interface is not intended to be extended by clients.
+ * @noinstantiate This class is not intended to be instantiated by clients.
  */
 public class LanguageSettingsDelta {
 	// maps need to be ordered by providers
@@ -28,6 +41,12 @@ public class LanguageSettingsDelta {
 	private LinkedHashMap<String, // providerId
 			LanguageSettingsStorage> newLanguageSettingsState;
 
+	/**
+	 * Constructor.
+	 *
+	 * @param oldState - old language settings storage state.
+	 * @param newState - new language settings storage state.
+	 */
 	public LanguageSettingsDelta(LinkedHashMap<String, LanguageSettingsStorage> oldState, LinkedHashMap<String, LanguageSettingsStorage> newState) {
 		oldLanguageSettingsState = oldState;
 		newLanguageSettingsState = newState;

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

@@ -7,6 +7,10 @@ import org.eclipse.core.resources.IResource;
 import org.eclipse.core.runtime.IStatus;
 import org.eclipse.core.runtime.Status;
 
+/**
+ *  Temporary class for logging language settings providers development.
+ *
+ */
 @Deprecated
 public class LanguageSettingsLogger {
 
@@ -15,7 +19,6 @@ public class LanguageSettingsLogger {
 //		return true;
 	}
 
-	// AG FIXME
 	/**
 	 * @param msg
 	 * @noreference This method is not intended to be referenced by clients.
@@ -29,7 +32,6 @@ public class LanguageSettingsLogger {
 		}
 	}
 
-	// AG FIXME
 	/**
 	 * @param msg
 	 * @noreference This method is not intended to be referenced by clients.
@@ -43,7 +45,6 @@ public class LanguageSettingsLogger {
 		}
 	}
 
-	// AG FIXME
 	/**
 	 * @param msg
 	 * @noreference This method is not intended to be referenced by clients.
@@ -56,8 +57,7 @@ public class LanguageSettingsLogger {
 			CCorePlugin.log(status);
 		}
 	}
-	
+
-	// AG FIXME
 	/**
 	 * @param rc
 	 * @param who - pass "this" (calling class instance) here

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

@@ -25,6 +25,9 @@ import org.w3c.dom.Element;
 import org.w3c.dom.Node;
 import org.w3c.dom.NodeList;
 
+/**
+ * The class representing persistent storage for language settings entries {@link ICLanguageSettingEntry}.
+ */
 public class LanguageSettingsSerializableStorage extends LanguageSettingsStorage {
 	private static final String ELEM_LANGUAGE = "language"; //$NON-NLS-1$
 	private static final String ATTR_LANGUAGE_ID = "id"; //$NON-NLS-1$
@@ -39,12 +42,13 @@ public class LanguageSettingsSerializableStorage extends LanguageSettingsStorage
 
 	/**
 	 * Serialize the provider entries under parent XML element.
+	 *
 	 * @param elementProvider - element where to serialize the entries.
 	 */
 	public void serializeEntries(Element elementProvider) {
 		synchronized (fStorage) {
 			for (Entry<String, Map<String, List<ICLanguageSettingEntry>>> entryLang : fStorage.entrySet()) {
-				serializeLanguage(elementProvider, entryLang);
+				serializeLanguage(elementProvider, entryLang.getKey(), entryLang.getValue());
 			}
 		}
 	}
@@ -52,27 +56,25 @@ public class LanguageSettingsSerializableStorage extends LanguageSettingsStorage
 	/**
 	 * Serialize the provider entries for a given language list.
 	 */
-	private void serializeLanguage(Element parentElement, Entry<String, Map<String, List<ICLanguageSettingEntry>>> entryLang) {
+	private void serializeLanguage(Element parentElement, String langId, Map<String, List<ICLanguageSettingEntry>> langMap) {
-		String langId = entryLang.getKey();
 		if (langId!=null) {
 			Element elementLanguage = XmlUtil.appendElement(parentElement, ELEM_LANGUAGE, new String[] {ATTR_LANGUAGE_ID, langId});
 			parentElement = elementLanguage;
 		}
-		for (Entry<String, List<ICLanguageSettingEntry>> entryRc : entryLang.getValue().entrySet()) {
+		for (Entry<String, List<ICLanguageSettingEntry>> entryRc : langMap.entrySet()) {
-			serializeResource(parentElement, entryRc);
+			serializeResource(parentElement, entryRc.getKey(), entryRc.getValue());
 		}
 	}
 
 	/**
 	 * Serialize the provider entries for a given resource list.
 	 */
-	private void serializeResource(Element parentElement, Entry<String, List<ICLanguageSettingEntry>> entryRc) {
+	private void serializeResource(Element parentElement, String rcProjectPath, List<ICLanguageSettingEntry> rcList) {
-		String rcProjectPath = entryRc.getKey();
 		if (rcProjectPath!=null) {
 			Element elementRc = XmlUtil.appendElement(parentElement, ELEM_RESOURCE, new String[] {ATTR_PROJECT_PATH, rcProjectPath});
 			parentElement = elementRc;
 		}
-		serializeSettingEntries(parentElement, entryRc.getValue());
+		serializeSettingEntries(parentElement, rcList);
 	}
 
 	/**
@@ -84,16 +86,16 @@ public class LanguageSettingsSerializableStorage extends LanguageSettingsStorage
 					ATTR_KIND, LanguageSettingEntriesSerializer.kindToString(entry.getKind()),
 					ATTR_NAME, entry.getName(),
 				});
-			switch(entry.getKind()) {
+			switch (entry.getKind()) {
 			case ICSettingEntry.MACRO:
 				elementSettingEntry.setAttribute(ATTR_VALUE, entry.getValue());
 				break;
 //			case ICLanguageSettingEntry.LIBRARY_FILE:
-//				// TODO: sourceAttachment fields may need to be covered
+//				// YAGNI: sourceAttachment fields may need to be covered
 //				break;
 			}
 			int flags = entry.getFlags();
-			if (flags!=0) {
+			if (flags != 0) {
 				// Element elementFlag =
 				XmlUtil.appendElement(elementSettingEntry, ELEM_FLAG, new String[] {
 						ATTR_VALUE, LanguageSettingEntriesSerializer.composeFlagsString(entry.getFlags())
@@ -104,14 +106,15 @@ public class LanguageSettingsSerializableStorage extends LanguageSettingsStorage
 
 	/**
 	 * Load provider entries from XML provider element.
-	 * @param providerNode - parent XML element <provider> where entries are defined.
+	 *
+	 * @param providerNode - parent XML element "provider" where entries are defined.
 	 */
 	public void loadEntries(Element providerNode) {
 		List<ICLanguageSettingEntry> settings = new ArrayList<ICLanguageSettingEntry>();
 		NodeList nodes = providerNode.getChildNodes();
 		for (int i=0;i<nodes.getLength();i++) {
 			Node elementNode = nodes.item(i);
-			if(elementNode.getNodeType() != Node.ELEMENT_NODE)
+			if (elementNode.getNodeType() != Node.ELEMENT_NODE)
 				continue;
 
 			if (ELEM_LANGUAGE.equals(elementNode.getNodeName())) {
@@ -126,7 +129,7 @@ public class LanguageSettingsSerializableStorage extends LanguageSettingsStorage
 			}
 		}
 		// set settings
-		if (settings.size()>0) {
+		if (settings.size() > 0) {
 			setSettingEntries(null, null, settings);
 		}
 	}
@@ -142,7 +145,7 @@ public class LanguageSettingsSerializableStorage extends LanguageSettingsStorage
 		int flags = 0;
 		for (int i=0;i<flagNodes.getLength();i++) {
 			Node flagNode = flagNodes.item(i);
-			if(flagNode.getNodeType() != Node.ELEMENT_NODE || !ELEM_FLAG.equals(flagNode.getNodeName()))
+			if (flagNode.getNodeType() != Node.ELEMENT_NODE || !ELEM_FLAG.equals(flagNode.getNodeName()))
 				continue;
 
 			String settingFlags = XmlUtil.determineAttributeValue(flagNode, ATTR_VALUE);
@@ -164,7 +167,7 @@ public class LanguageSettingsSerializableStorage extends LanguageSettingsStorage
 	 */
 	private void loadLanguageElement(Node parentNode, String cfgId) {
 		String langId = XmlUtil.determineAttributeValue(parentNode, ATTR_LANGUAGE_ID);
-		if (langId.length()==0) {
+		if (langId.length() == 0) {
 			langId=null;
 		}
 
@@ -172,7 +175,7 @@ public class LanguageSettingsSerializableStorage extends LanguageSettingsStorage
 		NodeList nodes = parentNode.getChildNodes();
 		for (int i=0;i<nodes.getLength();i++) {
 			Node elementNode = nodes.item(i);
-			if(elementNode.getNodeType() != Node.ELEMENT_NODE)
+			if (elementNode.getNodeType() != Node.ELEMENT_NODE)
 				continue;
 
 			if (ELEM_RESOURCE.equals(elementNode.getNodeName())) {
@@ -185,7 +188,7 @@ public class LanguageSettingsSerializableStorage extends LanguageSettingsStorage
 			}
 		}
 		// set settings
-		if (settings.size()>0) {
+		if (settings.size() > 0) {
 			setSettingEntries(null, langId, settings);
 		}
 	}
@@ -200,7 +203,7 @@ public class LanguageSettingsSerializableStorage extends LanguageSettingsStorage
 		NodeList nodes = parentNode.getChildNodes();
 		for (int i=0;i<nodes.getLength();i++) {
 			Node elementNode = nodes.item(i);
-			if(elementNode.getNodeType() != Node.ELEMENT_NODE)
+			if (elementNode.getNodeType() != Node.ELEMENT_NODE)
 				continue;
 
 			if (ELEM_ENTRY.equals(elementNode.getNodeName())) {
@@ -212,7 +215,7 @@ public class LanguageSettingsSerializableStorage extends LanguageSettingsStorage
 		}
 
 		// set settings
-		if (settings.size()>0) {
+		if (settings.size() > 0) {
 			setSettingEntries(rcProjectPath, langId, settings);
 		}
 	}