Merge pull request #201 from eharris/200-addMoreCommentsToCode

Issue #200: Add more comments to the code

Author: eharris369

dev/com.ibm.microclimate.core/src/com/ibm/microclimate/core/MicroclimateCorePlugin.java

@@ -31,8 +31,6 @@ public class MicroclimateCorePlugin extends AbstractUIPlugin {
 	public static final String DEFAULT_ICON_PATH = "icons/microclimate.ico"; //$NON-NLS-1$
 
 	public static final String
-			// Boolean option for hiding the on-finish dialog for the Link Project wizard
-			HIDE_ONFINISH_MSG_PREFSKEY = "showLinkWizardOnFinishDialog", //$NON-NLS-1$
 			// Int option for debug timeout in seconds
 			DEBUG_CONNECT_TIMEOUT_PREFSKEY = "serverDebugTimeout"; //$NON-NLS-1$
 
@@ -60,7 +58,6 @@ public void start(BundleContext context) throws Exception {
 		context.registerService(DebugOptionsListener.class, MCLogger.instance(), null);
 
 		// Set default preferences once, here
-		getPreferenceStore().setDefault(HIDE_ONFINISH_MSG_PREFSKEY, false);
 		getPreferenceStore().setDefault(DEBUG_CONNECT_TIMEOUT_PREFSKEY,
 				MCEclipseApplication.DEFAULT_DEBUG_CONNECT_TIMEOUT);
 	}

dev/com.ibm.microclimate.core/src/com/ibm/microclimate/core/internal/MCEclipseApplication.java

@@ -45,6 +45,11 @@
 import com.ibm.microclimate.core.internal.launch.MicroclimateLaunchConfigDelegate;
 import com.ibm.microclimate.core.internal.messages.Messages;
 
+/**
+ * Eclipse specific code for a Microclimate application.  Anything related to Eclipse 
+ * (launches, consoles, connecting the debugger, etc.) should go here and not in the
+ * MicroclimateApplication class.
+ */
 public class MCEclipseApplication extends MicroclimateApplication {
 
 	// Validation marker
@@ -150,10 +155,13 @@ public void reconnectDebugger() {
 
 	@Override
 	public void dispose() {
+		// Clean up the launch
 		if (launch != null) {
 			ILaunchManager launchManager = DebugPlugin.getDefault().getLaunchManager();
 			launchManager.removeLaunch(launch);
 		}
+		
+		// Clean up the consoles
 		List<IConsole> consoles = new ArrayList<IConsole>();
 		if (appConsole != null) {
 			consoles.add(appConsole);
@@ -170,6 +178,7 @@ public void dispose() {
 
 	@Override
 	public void resetValidation() {
+		// Delete all Microclimate markers for a project
 		IProject project = ResourcesPlugin.getWorkspace().getRoot().getProject(name);
 		if (project != null && project.isAccessible()) {
 			try {
@@ -191,7 +200,8 @@ public void validationWarning(String filePath, String message, String quickFixId
 	}
 
     private void validationEvent(int severity, String filePath, String message, String quickFixId, String quickFixDescription) {
-        try {
+        // Create a marker and quick fix (if available) on the specific file if there is one or the project if not.
+    	try {
         	IProject project = ResourcesPlugin.getWorkspace().getRoot().getProject(name);
         	if (project != null && project.isAccessible()) {
 	        	IResource resource = project;

dev/com.ibm.microclimate.core/src/com/ibm/microclimate/core/internal/MCUtil.java

@@ -131,20 +131,29 @@ public static int parsePort(String portStr) {
 		}
 	}
 
+	/**
+	 * Update everything in the Microclimate explorer view
+	 */
 	public static void updateAll() {
 		IUpdateHandler handler = MicroclimateCorePlugin.getUpdateHandler();
 		if (handler != null) {
 			handler.updateAll();
 		}
 	}
 
+	/**
+	 * Update the connection and its children in the Microclimate explorer view
+	 */
 	public static void updateConnection(MicroclimateConnection connection) {
 		IUpdateHandler handler = MicroclimateCorePlugin.getUpdateHandler();
 		if (handler != null) {
 			handler.updateConnection(connection);
 		}
 	}
 
+	/**
+	 * Update the application in the Microclimate explorer view
+	 */
 	public static void updateApplication(MicroclimateApplication app) {
 		IUpdateHandler handler = MicroclimateCorePlugin.getUpdateHandler();
 		if (handler != null) {

dev/com.ibm.microclimate.core/src/com/ibm/microclimate/core/internal/MicroclimateApplication.java

@@ -203,6 +203,11 @@ public synchronized void invalidatePorts() {
 		debugPort = -1;
 	}
 
+	/**
+	 * Get the capabilities of a project.  Cache them because they should not change
+	 * and since they are used to decide which menu items are shown/enabled this method
+	 * needs to be fast.
+	 */
 	public ProjectCapabilities getProjectCapabilities() {
 		if (projectCapabilities == null) {
 			try {
@@ -243,6 +248,7 @@ public void validationWarning(String filePath, String message, String quickFixId
 	}
 
 	public boolean supportsDebug() {
+		// Override as needed
 		return false;
 	}
 

dev/com.ibm.microclimate.core/src/com/ibm/microclimate/core/internal/MicroclimateObjectFactory.java

@@ -14,6 +14,13 @@
 import com.ibm.microclimate.core.internal.connection.MicroclimateConnection;
 import com.ibm.microclimate.core.internal.constants.ProjectType;
 
+/**
+ * Factory for creating the correct Microclimate objects.  This is used to keep the Eclipse
+ * code and the Microclimate code separate.
+ * 
+ * Currently only MicroclimateApplication has an Eclipse version.  Rather than let Eclipse
+ * code leak into MicroclimateConnection an Eclipse version of it should be created if necessary.
+ */
 public class MicroclimateObjectFactory {
 
 	public static MicroclimateConnection createMicroclimateConnection(URI uri) throws Exception {

dev/com.ibm.microclimate.core/src/com/ibm/microclimate/core/internal/connection/MicroclimateConnectionManager.java

@@ -15,9 +15,6 @@
 import java.util.Iterator;
 import java.util.List;
 
-import org.eclipse.jface.util.IPropertyChangeListener;
-import org.eclipse.jface.util.PropertyChangeEvent;
-
 import com.ibm.microclimate.core.MicroclimateCorePlugin;
 import com.ibm.microclimate.core.internal.MCLogger;
 import com.ibm.microclimate.core.internal.MCUtil;

dev/com.ibm.microclimate.core/src/com/ibm/microclimate/core/internal/connection/MicroclimateSocket.java

@@ -419,14 +419,18 @@ private void onValidationEvent(JSONObject event) throws JSONException {
 			MCLogger.logError("No application found for project: " + projectID);
 			return;
 		}
+		
+		// Clear out any old validation objects
 		app.resetValidation();
 
+		// If the validation is successful then just return
 		String status = event.getString(MCConstants.KEY_VALIDATION_STATUS);
 		if (MCConstants.VALUE_STATUS_SUCCESS.equals(status)) {
 			// Nothing to do
 			return;
 		}
 
+		// If the validation is not successful, create validation objects for each problem
 		if (event.has(MCConstants.KEY_VALIDATION_RESULTS)) {
 			JSONArray results = event.getJSONArray(MCConstants.KEY_VALIDATION_RESULTS);
 			for (int i = 0; i < results.length(); i++) {
@@ -458,6 +462,7 @@ private void onValidationEvent(JSONObject event) throws JSONException {
 	}
 
 	private boolean supportsQuickFix(MicroclimateApplication app, String type, String filename) {
+		// The regenerate job only works in certain cases so only show the quickfix in the working cases
 		if (!MCConstants.VALUE_TYPE_MISSING.equals(type) || app.projectType.isType(ProjectType.TYPE_DOCKER)) {
 			return false;
 		}

dev/com.ibm.microclimate.core/src/com/ibm/microclimate/core/internal/constants/ProjectCapabilities.java

@@ -18,6 +18,9 @@
 
 import com.ibm.microclimate.core.internal.MCLogger;
 
+/**
+ * Represents the capabilities of a project.
+ */
 public class ProjectCapabilities {
 
 	public static final ProjectCapabilities emptyCapabilities = new ProjectCapabilities();

dev/com.ibm.microclimate.core/src/com/ibm/microclimate/core/internal/constants/ProjectType.java

@@ -9,6 +9,9 @@
 
 package com.ibm.microclimate.core.internal.constants;
 
+/**
+ * Type and language of a project.
+ */
 public class ProjectType {
 
 	public static final String UNKNOWN = "unknown";

dev/com.ibm.microclimate.core/src/com/ibm/microclimate/core/internal/constants/StartMode.java

@@ -15,6 +15,9 @@
 
 import com.ibm.microclimate.core.internal.MCLogger;
 
+/**
+ * Project start modes.
+ */
 public enum StartMode {
 
 	RUN("run"),