diff --git a/core/org.eclipse.cdt.core/model/org/eclipse/cdt/core/settings/model/CProjectDescriptionEvent.java b/core/org.eclipse.cdt.core/model/org/eclipse/cdt/core/settings/model/CProjectDescriptionEvent.java
index 52eab71257f..1744c26e494 100644
--- a/core/org.eclipse.cdt.core/model/org/eclipse/cdt/core/settings/model/CProjectDescriptionEvent.java
+++ b/core/org.eclipse.cdt.core/model/org/eclipse/cdt/core/settings/model/CProjectDescriptionEvent.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2007 Intel Corporation and others.
+ * Copyright (c) 2007, 2010 Intel Corporation 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
@@ -16,30 +16,46 @@ import org.eclipse.core.resources.IProject;
 
 /**
  * Events fired for the project delats.
- * 
- * FIXME JBB: Should work out the difference between DATA_APPLIED AND APPLIED events
- * current DATA_APPLIED occurs first and fNewDescription is modified. Need to clearly define
- * the project description state transitions
+ * The ProjectDescription lifecycle looks like:
+ * <ul>
+ * <li>
+ *   - {@link #LOADED} - configuration is loaded and read-only
+ * <li>
+ *   - {@link #COPY_CREATED} - Indicates new writable description has been created from
+ *                     the read-only description backing store
+ * <li>
+ *   - {@link #ABOUT_TO_APPLY} - First event in the setProjectDescription flow. New description
+ *                      writable, old description represents the cache
+ * <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>
  */
 
 public final class CProjectDescriptionEvent {
+	/** Event kind indicating project description has loaded */
 	public static final int LOADED = 1;
+	/** Event kind indicating we're about to set the project description */
 	public static final int ABOUT_TO_APPLY = 1 << 1;
 	public static final int APPLIED = 1 << 2;
+	/** Event kind indicating a copy of the description has been created */
 	public static final int COPY_CREATED = 1 << 3;
 	public static final int DATA_APPLIED = 1 << 4;
+	/** Event kind encapsulated ALL events */
 	public static final int ALL = LOADED | ABOUT_TO_APPLY | APPLIED | COPY_CREATED | DATA_APPLIED;
 	
-	private int fType;
+	/** The type of event this corresponds to */ 
+	private final int fType;
 	/** A *writable* new description */
-	private ICProjectDescription fNewDescription;
+	private final ICProjectDescription fNewDescription;
 	/** The previous description should be read-only */
-	private ICProjectDescription fOldDescription;
-	private ICProjectDescription fAppliedDescription;
-	private ICDescriptionDelta fProjDelta;
+	private final ICProjectDescription fOldDescription;
+	private final ICProjectDescription fAppliedDescription;
+	private final ICDescriptionDelta fProjDelta;
 	private ICDescriptionDelta fActiveCfgDelta;
 	private ICDescriptionDelta fIndexCfgDelta;
-	private IProject fProject;
+	private final IProject fProject;
 	
 	public CProjectDescriptionEvent(int type,
 			ICDescriptionDelta delta,
@@ -55,6 +71,8 @@ public final class CProjectDescriptionEvent {
 			fProject = fNewDescription.getProject();
 		} else if (fOldDescription != null) {
 			fProject = fOldDescription.getProject();
+		} else {
+			fProject = null;
 		}
 	}
 	
@@ -144,18 +162,24 @@ public final class CProjectDescriptionEvent {
 		return null;
 	}
 
+	/**
+	 * @return return the previous project description, may be null
+	 */
 	public ICProjectDescription getOldCProjectDescription() {
 		return fOldDescription;
 	}
 
 	/**
-	 * Return the new description which is writeable
-	 * @return writable new description
+	 * Return the new description which may be writeable (depending on the event type)
+	 * @return new project description
 	 */
 	public ICProjectDescription getNewCProjectDescription() {
 		return fNewDescription;
 	}
 
+	/**
+	 * @return the applied project description, may be null
+	 */
 	public ICProjectDescription getAppliedCProjectDescription() {
 		return fAppliedDescription;
 	}