diff --git a/terminal/org.eclipse.tm.terminal/src/org/eclipse/tm/internal/terminal/connector/TerminalConnector.java b/terminal/org.eclipse.tm.terminal/src/org/eclipse/tm/internal/terminal/connector/TerminalConnector.java
index 869b5ded7c2..79b901bfedd 100644
--- a/terminal/org.eclipse.tm.terminal/src/org/eclipse/tm/internal/terminal/connector/TerminalConnector.java
+++ b/terminal/org.eclipse.tm.terminal/src/org/eclipse/tm/internal/terminal/connector/TerminalConnector.java
@@ -15,8 +15,9 @@ import org.eclipse.tm.internal.terminal.provisional.api.TerminalState;
 import org.eclipse.tm.internal.terminal.provisional.api.provider.TerminalConnectorImpl;
 
 /**
- * A terminal connector instance, also known as terminal connection type.
- * 
+ * An {@link ITerminalConnector} instance, also known as terminal connection
+ * type, for maintaining a single terminal connection.
+ *
  * It provides all terminal connector functions that can be provided by static
  * markup without loading the actual implementation class. The actual
  * {@link TerminalConnectorImpl} implementation class is lazily loaded by the
@@ -26,7 +27,7 @@ import org.eclipse.tm.internal.terminal.provisional.api.provider.TerminalConnect
  * {@link #getId()}, {@link #getName()}, {@link #getSettingsSummary()},{@link #load(ISettingsStore)},
  * {@link #setTerminalSize(int, int)}, {@link #save(ISettingsStore)},
  * {@link #getAdapter(Class)}
- * 
+ *
  * @noextend This class is not intended to be subclassed by clients.
  * @noinstantiate This class is not intended to be instantiated by clients.
  *                Clients can get terminal connector instances through the
@@ -51,7 +52,7 @@ public class TerminalConnector implements ITerminalConnector {
 		TerminalConnectorImpl makeConnector() throws Exception;
 	}
 	/**
-	 *
+	 * The factory for creating impl instances.
 	 */
 	private final TerminalConnector.Factory fTerminalConnectorFactory;
 	/**
@@ -77,9 +78,13 @@ public class TerminalConnector implements ITerminalConnector {
 	 */
 	private ISettingsStore fStore;
 	/**
-	 * @param terminalConnectorFactory
-	 * @param id
-	 * @param name
+	 * Constructor for the terminal connector.
+	 *
+	 * @param terminalConnectorFactory Factory for lazily instantiating the
+	 *            TerminalConnectorImpl when needed.
+	 * @param id terminal connector ID. The connector is publicly known under
+	 *            this ID.
+	 * @param name translatable name to display the connector in the UI.
 	 */
 	public TerminalConnector(TerminalConnector.Factory terminalConnectorFactory, String id, String name) {
 		fTerminalConnectorFactory = terminalConnectorFactory;
diff --git a/terminal/org.eclipse.tm.terminal/src/org/eclipse/tm/internal/terminal/provisional/api/provider/TerminalConnectorImpl.java b/terminal/org.eclipse.tm.terminal/src/org/eclipse/tm/internal/terminal/provisional/api/provider/TerminalConnectorImpl.java
index 0edf1980127..50359d45733 100644
--- a/terminal/org.eclipse.tm.terminal/src/org/eclipse/tm/internal/terminal/provisional/api/provider/TerminalConnectorImpl.java
+++ b/terminal/org.eclipse.tm.terminal/src/org/eclipse/tm/internal/terminal/provisional/api/provider/TerminalConnectorImpl.java
@@ -24,12 +24,19 @@ import org.eclipse.tm.internal.terminal.provisional.api.ITerminalControl;
  * @since org.eclipse.tm.terminal 2.0
  */
 public abstract class TerminalConnectorImpl {
+
 	/**
-	 * Called once after the constructor
-	 * @throws Exception
+	 * Initialize this connector. This is called once after the constructor, in
+	 * order to perform any required initializations such as loading required
+	 * native libraries. Any work that may lead to runtime exceptions should be
+	 * done in this method rather than in the constructor.
+	 *
+	 * @throws Exception when the connector fails to initialize (due to missing
+	 *             required libraries, for instance).
 	 */
 	public void initialize() throws Exception {
 	}
+
 	/**
 	 * Connect using the current state of the settings.
 	 * @param control Used to inform the UI about state changes and messages from the connection.
@@ -79,18 +86,21 @@ public abstract class TerminalConnectorImpl {
 	 * store the state of the connection.
 	 */
 	abstract public void load(ISettingsStore store);
+
 	/**
-	 * When the view or dialog containing the terminal is closed,
-	 * the state of the connection is saved into the settings store <code>store</code>
-	 * @param store
+	 * When the view or dialog containing the terminal is closed, the state of
+	 * the connection is saved into the settings store <code>store</code>
+	 *
+	 * @param store the store for persisting settings.
 	 */
 	abstract public void save(ISettingsStore store);
 
     /**
-     * Notify the remote site that the size of the terminal has changed.
-     * @param newWidth
-     * @param newHeight
-     */
+	 * Notify the remote site that the size of the terminal has changed.
+	 *
+	 * @param newWidth the new width in characters.
+	 * @param newHeight the new height in characters.
+	 */
 	public void setTerminalSize(int newWidth, int newHeight) {
 	}
 }