JavaDoc ICConfigurationDescription

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

@@ -10,27 +10,29 @@
  *******************************************************************************/
 package org.eclipse.cdt.core.settings.model;
 
+import org.eclipse.cdt.internal.core.settings.model.CConfigurationDescription;
+import org.eclipse.cdt.internal.core.settings.model.CConfigurationDescriptionCache;
 import org.eclipse.cdt.internal.core.settings.model.CProjectDescriptionDelta;
 import org.eclipse.cdt.internal.core.settings.model.CProjectDescriptionManager;
 import org.eclipse.core.resources.IProject;
 
 /**
- * Events fired for the project delats.
+ * Events fired for the project deltas.
- * The ProjectDescription lifecycle looks like:
+ * The ProjectDescription life-cycle looks like:
  * <ul>
- * <li>
+ * <li> {@link #LOADED} - configuration is loaded and read-only.
- *   - {@link #LOADED} - configuration is loaded and read-only
+ * <li> {@link #COPY_CREATED} - Indicates new writable description has been created
- * <li>
+ *         from the read-only description backing store.
- *   - {@link #COPY_CREATED} - Indicates new writable description has been created from
+ * <li> {@link #ABOUT_TO_APPLY} - First event in the setProjectDescription flow.
- *                     the read-only description backing store
+ *         New description writable, old description represents the cache.
- * <li>
+ * <li> {@link #DATA_APPLIED} - Event indicating that configuration data has been applied
- *   - {@link #ABOUT_TO_APPLY} - First event in the setProjectDescription flow. New description
+ *         by the build system.
- *                      writable, old description represents the cache
+ * <li> {@link #APPLIED} - setProjectDescription finished, newDescription is read-only.
- * <li>
- *   - {@link #DATA_APPLIED} - Event indicating that configuration data has been applied by the build system
- * <li>
- *   - {@link #APPLIED} - setProjectDescription finished, newDescription is read-only
  * </ul>
+ *
+ * @see ICConfigurationDescription
+ * @see CConfigurationDescription
+ * @see CConfigurationDescriptionCache
  */
 
 public final class CProjectDescriptionEvent {

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

@@ -16,13 +16,29 @@ import org.eclipse.cdt.core.cdtvariables.ICdtVariablesContributor;
 import org.eclipse.cdt.core.model.CoreModel;
 import org.eclipse.cdt.core.settings.model.extension.CConfigurationData;
 import org.eclipse.cdt.core.settings.model.extension.CConfigurationDataProvider;
+import org.eclipse.cdt.internal.core.settings.model.CConfigurationDescription;
+import org.eclipse.cdt.internal.core.settings.model.CConfigurationDescriptionCache;
 import org.eclipse.core.runtime.CoreException;
 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 class representing configuration and thus this is the root element
- * for configuration-specific settings
+ * for configuration-specific settings.
+ * <br><br>
+ * A typical (simplified) life-cycle of configuration description in CDT is as following:
+ * <br> 1. A project is created or opened. A new read-only configuration description is loaded.
+ * <br> 2. If a description needs to be changed, a client gets a copy as a writable configuration
+ *         description first. Then, that instance can be edited.
+ * <br> 3. The changed writable configuration description gets applied to the model and becomes
+ *         read-only.
+ * <br> 4. The project gets closed or removed. The configuration description gets disposed.
+ * <br><br>
+ * Typically read-only configuration description would be represented by {@link CConfigurationDescriptionCache}
+ * and writable one by {@link CConfigurationDescription}.
+ *
+ * @see CProjectDescriptionEvent
+ * @see CConfigurationDescriptionCache
  */
 public interface ICConfigurationDescription extends ICSettingContainer, ICSettingObject, ICSettingsStorage {
 	/**

core/org.eclipse.cdt.core/model/org/eclipse/cdt/internal/core/settings/model/CConfigurationDescription.java

@@ -21,6 +21,7 @@ import org.eclipse.cdt.core.cdtvariables.ICdtVariablesContributor;
 import org.eclipse.cdt.core.language.settings.providers.ILanguageSettingsProvider;
 import org.eclipse.cdt.core.language.settings.providers.ILanguageSettingsProvidersKeeper;
 import org.eclipse.cdt.core.settings.model.CConfigurationStatus;
+import org.eclipse.cdt.core.settings.model.CProjectDescriptionEvent;
 import org.eclipse.cdt.core.settings.model.ICBuildSetting;
 import org.eclipse.cdt.core.settings.model.ICConfigExtensionReference;
 import org.eclipse.cdt.core.settings.model.ICConfigurationDescription;
@@ -52,6 +53,13 @@ import org.eclipse.core.runtime.CoreException;
 import org.eclipse.core.runtime.IPath;
 import org.eclipse.core.runtime.QualifiedName;
 
+/**
+ * The writable configuration description.
+ *
+ * @see ICConfigurationDescription
+ * @see CConfigurationDescriptionCache
+ * @see CProjectDescriptionEvent
+ */
 public class CConfigurationDescription extends CDataProxyContainer
 		implements ICConfigurationDescription, IProxyFactory, IInternalCCfgInfo, ILanguageSettingsProvidersKeeper {
 	private CfgProxyCache fCache;

core/org.eclipse.cdt.core/model/org/eclipse/cdt/internal/core/settings/model/CConfigurationDescriptionCache.java

@@ -19,6 +19,7 @@ import org.eclipse.cdt.core.cdtvariables.ICdtVariablesContributor;
 import org.eclipse.cdt.core.language.settings.providers.ILanguageSettingsProvider;
 import org.eclipse.cdt.core.language.settings.providers.ILanguageSettingsProvidersKeeper;
 import org.eclipse.cdt.core.settings.model.CConfigurationStatus;
+import org.eclipse.cdt.core.settings.model.CProjectDescriptionEvent;
 import org.eclipse.cdt.core.settings.model.ICBuildSetting;
 import org.eclipse.cdt.core.settings.model.ICConfigExtensionReference;
 import org.eclipse.cdt.core.settings.model.ICConfigurationDescription;
@@ -60,22 +61,34 @@ import org.eclipse.core.runtime.QualifiedName;
  *
  * An inspection of the scenario where user changes project properties and saves it yields
  * following sequence of events:
- * - Initialization:
+ * <ol>
- *   - After eclipse started a project is being opened. A new CConfigurationDescriptionCache is created
+ * <li> Initialization:
+ *   <ul>
+ *   <li> After eclipse started a project is being opened. A new CConfigurationDescriptionCache is created
  *        with CConfigurationDescriptionCache(ICStorageElement storage, CProjectDescription parent) constructor.
- *   - Any clients needed ICConfigurationDescription get CConfigurationDescription using constructor
+ *   <li> Any clients needed ICConfigurationDescription get CConfigurationDescription using constructor
  *        CConfigurationDescription(CConfigurationData data, String buildSystemId, ICDataProxyContainer cr)
  *        where the CConfigurationDescriptionCache is passed as data. The reference to cache is kept in field fCfgCache.
- *   - fCfgCache is used to getSpecSettings() CConfigurationSpecSettings, after that fCfgCache is set to null.
+ *   <li> fCfgCache is used to getSpecSettings() CConfigurationSpecSettings, after that fCfgCache is set to null.
- * - User enters project properties/settings:
+ *   </ul>
- *   - another CConfigurationDescription (settings configuration) created using the same constructor setting fCfgCache
+ * <li> User enters project properties/settings:
+ *   <ul>
+ *   <li> another CConfigurationDescription (settings configuration) created using the same constructor setting fCfgCache
  *        to the CConfigurationDescriptionCache.
- * - User changes settings (in the settings configuration CConfigurationDescription) and saves it:
+ *   </ul>
- *   - new CConfigurationDescriptionCache is created from the CConfigurationDescription via constructor
+ * <li> User changes settings (in the settings configuration CConfigurationDescription) and saves it:
+ *   <ul>
+ *   <li> new CConfigurationDescriptionCache is created from the CConfigurationDescription via constructor
  *        CConfigurationDescriptionCache(ICConfigurationDescription baseDescription, ...) where
  *        baseDescription is saved as fBaseDescription.
- *   - CConfigurationDescriptionCache.applyData(...) is used to persist the data. at that point
+ *   <li> CConfigurationDescriptionCache.applyData(...) is used to persist the data. at that point
  *        reference fBaseDescription gets set to null.
+ *   </ul>
+ * </ol>
+ *
+ * @see ICConfigurationDescription
+ * @see CConfigurationDescription
+ * @see CProjectDescriptionEvent
  */
 public class CConfigurationDescriptionCache extends CDefaultConfigurationData
 		implements ICConfigurationDescription, IInternalCCfgInfo, ILanguageSettingsProvidersKeeper, ICachedData {