Bug 488959 - API and extension point documentation

Change-Id: Ie7ce292ab14d11f06f3e4eb2f719704ddb2dae0c
Signed-off-by: Jonathan Williams <jonwilliams@qnx.com>

bundles/org.eclipse.remote.console/schema/consoleToolbar.exsd

@@ -6,7 +6,7 @@
          <meta.schema plugin="org.eclipse.remote.console" id="org.eclipse.remote.console.toolbar" name="Terminal Console Toolbar Contributions"/>
       </appinfo>
       <documentation>
-         [Enter description of this extension point.]
+         This extension point allows contributions to the TerminalConsole for various types of connections. It associates an action id with a connection type and factory.
       </documentation>
    </annotation>
 
@@ -76,21 +76,20 @@
       </complexType>
    </element>
 
-   <annotation>
-      <appinfo>
-         <meta.section type="since"/>
-      </appinfo>
-      <documentation>
-         [Enter the first release in which this extension point appears.]
-      </documentation>
-   </annotation>
 
    <annotation>
       <appinfo>
          <meta.section type="examples"/>
       </appinfo>
       <documentation>
-         [Enter extension point usage example here.]
+            &lt;extension
+         point=&quot;org.eclipse.remote.console.toolbar&quot;&gt;
+      &lt;action
+            actionFactory=&quot;com.example.actions.MyActionFactory&quot;
+            connectionType=&quot;org.eclipse.remote.serial.core.connectionType&quot;
+            id=&quot;com.example.actions.MyAction&quot;&gt;
+      &lt;/action&gt;
+   &lt;/extension&gt;
       </documentation>
    </annotation>
 
@@ -99,7 +98,9 @@
          <meta.section type="apiinfo"/>
       </appinfo>
       <documentation>
-         [Enter API information here.]
+         The value of the actionFactory attribute must implement the abstract class &lt;code&gt;org.eclipse.remote.console.ConsoleAction&lt;/code&gt;
+
+The value of the connectionType attribute should reference the id of a connectionType under the org.eclipse.remote.core.remoteServices extension point.
       </documentation>
    </annotation>
 
@@ -108,9 +109,26 @@
          <meta.section type="implementation"/>
       </appinfo>
       <documentation>
-         [Enter information about supplied implementation of this extension point.]
+         The package itself does not have any predefined toolbar contributions.
       </documentation>
    </annotation>
 
+   <annotation>
+      <appinfo>
+         <meta.section type="copyright"/>
+      </appinfo>
+      <documentation>
+         /*******************************************************************************
+ * Copyright (c) 2016 QNX Software Systems 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
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ * QNX Software Systems - Initial API and implementation
+ *******************************************************************************/
+      </documentation>
+   </annotation>
 
 </schema>

bundles/org.eclipse.remote.console/src/org/eclipse/remote/console/actions/ConsoleAction.java

@@ -16,32 +16,96 @@ import org.eclipse.jface.resource.ImageRegistry;
 import org.eclipse.remote.internal.console.Activator;
 
 /**
+ * An abstract class to implement basic functionality common to terminal console actions
  * @since 1.1
  */
 public abstract class ConsoleAction extends Action {
+
+	/**
+	 * @param id
+	 * 			The action id 
+	 */
 	public ConsoleAction(String id) {
 		this(id, 0);
 	}
 
+	/**
+	 * @param id
+	 * 			The action id 
+	 * @param style
+	 * 			one of AS_PUSH_BUTTON, AS_CHECK_BOX, AS_DROP_DOWN_MENU, AS_RADIO_BUTTON, 
+	 *  and AS_UNSPECIFIED
+	 */
 	public ConsoleAction(String id, int style) {
 		super("", style); //$NON-NLS-1$
 		setId(id);
 	}
 
-	protected void setupAction(String text, String tooltip, String image, String enabledImage, String disabledImage,
+	/**
+	 * @param text
+	 * 			the text for this action
+	 * @param tooltip
+	 * 			the tooltip for this action
+	 * @param image
+	 * 			the image key for this action
+	 * @param enabledImage
+	 * 			the enabled image key for this action
+	 * @param disabledImage
+	 * 			the disabled image key for this action
+	 * @param enabled
+	 * 			the enabled state for this action
+	 */
+	protected void setupAction(String text, String tooltip,
+			String image, String enabledImage, String disabledImage,
 			boolean enabled) {
 		ImageRegistry imageRegistry = Activator.getDefault().getImageRegistry();
 		setupAction(text, tooltip, image, enabledImage, disabledImage, enabled, imageRegistry);
 	}
 
-	protected void setupAction(String text, String tooltip, String hoverImage, String enabledImage,
+	/**
-			String disabledImage, boolean enabled, ImageRegistry imageRegistry) {
+	 * @param text
-		setupAction(text, tooltip, imageRegistry.getDescriptor(hoverImage), imageRegistry.getDescriptor(enabledImage),
+	 * 			the text for this action
-				imageRegistry.getDescriptor(disabledImage), enabled);
+	 * @param tooltip
+	 * 			the tooltip for this action
+	 * @param hoverImage
+	 * 			the hover image key for this action
+	 * @param enabledImage
+	 * 			the enabled image key for this action
+	 * @param disabledImage
+	 * 			the disabled image key for this action
+	 * @param enabled
+	 * 			the enabled state for this action
+	 * @param imageRegistry
+	 * 			the ImageRegistry to retrieve ImageDescriptor for the keys provided
+	 */
+	protected void setupAction(String text, String tooltip,
+			String hoverImage, String enabledImage, String disabledImage,
+			boolean enabled, ImageRegistry imageRegistry) {
+		setupAction(text,
+				tooltip,
+				imageRegistry.getDescriptor(hoverImage),
+				imageRegistry.getDescriptor(enabledImage),
+				imageRegistry.getDescriptor(disabledImage),
+				enabled);
 	}
 
-	protected void setupAction(String text, String tooltip, ImageDescriptor hoverImage, ImageDescriptor enabledImage,
+	/**
-			ImageDescriptor disabledImage, boolean enabled) {
+	 * @param text
+	 * 			the text for this action
+	 * @param tooltip
+	 * 			the tooltip for this action
+	 * @param hoverImage
+	 * 			the hover image for this action
+	 * @param enabledImage
+	 * 			the enabled image for this action
+	 * @param disabledImage
+	 * 			the disabled image for this action
+	 * @param enabled
+	 * 			the enabled state for this action
+	 */
+	protected void setupAction(String text, String tooltip,
+			ImageDescriptor hoverImage, ImageDescriptor enabledImage, ImageDescriptor disabledImage,
+			boolean enabled) {
 		setText(text);
 		setToolTipText(tooltip);
 		setEnabled(enabled);

bundles/org.eclipse.remote.console/src/org/eclipse/remote/console/actions/IConsoleActionFactory.java

@@ -16,5 +16,16 @@ import org.eclipse.core.runtime.IAdaptable;
  * @since 1.1
  */
 public interface IConsoleActionFactory {
+	/** 
+	 * Returns an implementation of ConsoleAction
+	 * 
+	 * @param actionId
+	 * 				The id of the action being requested 
+	 * @param connectionType
+	 * 				The connection type of the terminal console
+	 * @param adapter
+	 * 				An adapter to get relevant objects for use by the ConsoleAction being created (eg. IRemoteConnection) 
+	 * @return an implementation of ConsoleAction
+	 */
 	public ConsoleAction createAction(String actionId, String connectionType, IAdaptable adapter);
 }