# HG changeset patch
# User timkelly
# Date 1265997342 21600
# Node ID cb7b077cee273cfae075c20b19987635f3337491
# Parent  18229ce040aa913efe10bb0bc2a98f82f7ed1cfa
add comments for new code under bug 10681.

diff -r 18229ce040aa -r cb7b077cee27 core/com.nokia.carbide.cpp.sdk.core/plugin.xml
--- a/core/com.nokia.carbide.cpp.sdk.core/plugin.xml	Fri Feb 12 09:58:21 2010 -0600
+++ b/core/com.nokia.carbide.cpp.sdk.core/plugin.xml	Fri Feb 12 11:55:42 2010 -0600
@@ -30,6 +30,7 @@
       </scriptableClass>
    </extension>
 
+  <!-- Convenience extension so clients can know when the SDKs have loaded to avoid earlyStartup -->
   <extension-point id="sdkManagerLoadedHook" name="SDKManager Available Notification"/>
 
 </plugin>
diff -r 18229ce040aa -r cb7b077cee27 core/com.nokia.carbide.cpp.sdk.core/src/com/nokia/carbide/cpp/internal/api/sdk/ISDKManagerLoadedHook.java
--- a/core/com.nokia.carbide.cpp.sdk.core/src/com/nokia/carbide/cpp/internal/api/sdk/ISDKManagerLoadedHook.java	Fri Feb 12 09:58:21 2010 -0600
+++ b/core/com.nokia.carbide.cpp.sdk.core/src/com/nokia/carbide/cpp/internal/api/sdk/ISDKManagerLoadedHook.java	Fri Feb 12 11:55:42 2010 -0600
@@ -18,7 +18,8 @@
 public interface ISDKManagerLoadedHook {
 	
 	/**
-	 * Feature to notify that SDKs are loade
+	 * Feature to notify that SDKs are loaded the first time.
+	 * For subsequent SDK scan notifications see {@link com.nokia.carbide.cdt.builder.project.ICarbideConfigurationChangedListener}
 	 */
 	public void symbianSDKManagerLoaded();
 	
diff -r 18229ce040aa -r cb7b077cee27 qt/com.nokia.carbide.cpp.qt.core/src/com/nokia/carbide/cpp/internal/qt/core/QtCorePlugin.java
--- a/qt/com.nokia.carbide.cpp.qt.core/src/com/nokia/carbide/cpp/internal/qt/core/QtCorePlugin.java	Fri Feb 12 09:58:21 2010 -0600
+++ b/qt/com.nokia.carbide.cpp.qt.core/src/com/nokia/carbide/cpp/internal/qt/core/QtCorePlugin.java	Fri Feb 12 11:55:42 2010 -0600
@@ -125,10 +125,16 @@
 		job.schedule();
 	}
 
+	/**
+	 * ISDKManagerLoadedHook extension implementation
+	 */
 	public void symbianSDKManagerLoaded() {
 		scanForQtSDKs();
 	}
 
+	/**
+	 * Implements ICarbideInstalledSDKChangeListener. Ensures the Qt-SDK list is up to date with scanned Symbian SDKs
+	 */
 	public void installedSdkChanged(SDKChangeEventType eventType) {
 		scanForQtSDKs();
 	}
diff -r 18229ce040aa -r cb7b077cee27 qt/com.nokia.carbide.cpp.qt.core/src/com/nokia/carbide/cpp/internal/qt/core/QtSDKUtils.java
--- a/qt/com.nokia.carbide.cpp.qt.core/src/com/nokia/carbide/cpp/internal/qt/core/QtSDKUtils.java	Fri Feb 12 09:58:21 2010 -0600
+++ b/qt/com.nokia.carbide.cpp.qt.core/src/com/nokia/carbide/cpp/internal/qt/core/QtSDKUtils.java	Fri Feb 12 11:55:42 2010 -0600
@@ -15,9 +15,7 @@
 import java.io.File;
 import java.util.ArrayList;
 import java.util.List;
-import java.util.logging.Logger;
 
-import org.eclipse.core.internal.runtime.Log;
 import org.eclipse.core.resources.IProject;
 import org.eclipse.core.resources.ResourcesPlugin;
 import org.eclipse.core.runtime.CoreException;
@@ -28,15 +26,20 @@
 import org.eclipse.jface.preference.IPreferenceStore;
 
 import com.nokia.carbide.cpp.sdk.core.ISymbianSDK;
-import com.nokia.carbide.cpp.sdk.core.SDKCorePlugin;
 import com.nokia.cpp.internal.api.utils.core.HostOS;
 import com.nokia.cpp.internal.api.utils.core.Logging;
 import com.trolltech.qtcppproject.QtProjectPlugin;
 import com.trolltech.qtcppproject.preferences.PreferenceConstants;
 
+/**
+ * Wrapper utils for the Qt-ecilpse integration and obtaining information about internally installed Qt-sdks
+ */
 @SuppressWarnings({ "restriction" })
 public class QtSDKUtils {
 	
+	/**
+	 * Represents one Qt-SDK from the Qt global preferences
+	 */
 	private static class QtSDK {
 		
 		QtSDK(String name, String incPath, String binPath){
@@ -68,6 +71,11 @@
 	// private data from QtProject.java
 	private static final String QTVERSION = "com.trolltech.qtcppproject.properties.qtversion";
 	
+	/**
+	 * For the given Symbian SDK, test whether or not it qualifies for have Qt internally built.
+	 * @param sdk - The Symbian SDK or source base to test
+	 * @return - true if Qt is internally installed
+	 */
 	static private boolean isQtInternallyInstalled(ISymbianSDK sdk){
 		
 		String epocRoot = sdk.getEPOCROOT();
@@ -86,6 +94,11 @@
 		return false;
 	}
 	
+	/**
+	 * For the given Symbian SDK, get the Qt SDK name from the Qt global preferences.
+	 * @param sdk
+	 * @return The Qt SDK display name in the preferences, null if not found
+	 */
 	static public String getQtSDKNameForSymbianSDK(ISymbianSDK sdk){
 		
 		String epocRoot = sdk.getEPOCROOT();
@@ -110,6 +123,12 @@
 		return null;
 	}
 	
+	/**
+	 * Add a single Qt-SDK BIN and INLCUDE path to the Qt global preferences iff it is an internally built
+	 * Qt-SDK and the BIN and INC path do not already exist.
+	 * @param sdk
+	 * @param makeDefault - Set the default name in the global Qt prefs
+	 */
 	static public void addQtSDKForSymbianSDK(ISymbianSDK sdk, boolean makeDefault){
 	
 		refreshQtStoredSDKs();
@@ -120,6 +139,13 @@
 		}
 	}
 	
+	/**
+	 * Add a Qt-SDK to the Qt global preferences
+	 * @param name
+	 * @param binPath
+	 * @param incPath
+	 * @param makeDefault
+	 */
 	static private void addQtSDK(String name, IPath binPath, IPath incPath, boolean makeDefault){
 
 		IPreferenceStore store = QtProjectPlugin.getDefault().getPreferenceStore();
@@ -147,6 +173,9 @@
 		refreshQtStoredSDKs();
 	}
 	
+	/**
+	 * Update the internal list of Qt-SDKs found in the Qt global preferences
+	 */
 	static void refreshQtStoredSDKs(){
 		
 		qtSDKList.clear();
@@ -178,10 +207,22 @@
 		}
 	}
 	
+	/**
+	 * This method assumes the IProject has a Qt nature and sets the QTVERSION in the Qt project settings panel
+	 * @param project
+	 * @param qtSDKName
+	 * @throws CoreException
+	 */
 	public static void setDefaultQtSDKForProject(IProject project, String qtSDKName) throws CoreException{
 		project.setPersistentProperty(new QualifiedName("", QTVERSION), qtSDKName);
 	}
 	
+	/**
+	 * Assuming a Qt project, this retrieves the Qt project setting for the currently set Qt-SDK
+	 * @param project
+	 * @return
+	 * @throws CoreException
+	 */
 	public static String getDefaultQtSDKForProject(IProject project) throws CoreException{
 		return project.getPersistentProperty(new QualifiedName("", QTVERSION));
 	}
diff -r 18229ce040aa -r cb7b077cee27 qt/com.nokia.carbide.cpp.qt.ui/src/com/nokia/carbide/cpp/internal/qt/ui/QtUIPlugin.java
--- a/qt/com.nokia.carbide.cpp.qt.ui/src/com/nokia/carbide/cpp/internal/qt/ui/QtUIPlugin.java	Fri Feb 12 09:58:21 2010 -0600
+++ b/qt/com.nokia.carbide.cpp.qt.ui/src/com/nokia/carbide/cpp/internal/qt/ui/QtUIPlugin.java	Fri Feb 12 11:55:42 2010 -0600
@@ -147,10 +147,19 @@
 		}
 	}
 	
+	/** 
+	 * Implements ICarbideConfigurationChangedListener
+	 */
 	public void buildConfigurationChanged(ICarbideBuildConfiguration currentConfig) {
 		checkDefaultQtSDKForProject(currentConfig);
 	}
 	
+	/**
+	 * For the newly selected build configuration, check and see if there's an analogous internally installed
+	 * Qt-SDK, and if so make that the default. The default should not change if already set to &ltDefault&gt in the qt preferences or
+	 * if the new configuration has no internally built Qt-SDK.
+	 * @param currentConfig
+	 */
 	@SuppressWarnings("restriction")
 	private void checkDefaultQtSDKForProject(ICarbideBuildConfiguration currentConfig){
 		IProject project = currentConfig.getCarbideProject().getProject();
@@ -172,6 +181,9 @@
 		
 	}
 
+	/** 
+	 * Implements ISDKManagerLoadedHook
+	 */
 	public void symbianSDKManagerLoaded() {
 		CarbideBuilderPlugin.addBuildConfigChangedListener(this);
 	}