Bug 488959 - API and extension point documentation
Change-Id: Ie7ce292ab14d11f06f3e4eb2f719704ddb2dae0c
Signed-off-by: Jonathan Williams <jonwilliams@qnx.com>
diff --git a/bundles/org.eclipse.remote.console/schema/consoleToolbar.exsd b/bundles/org.eclipse.remote.console/schema/consoleToolbar.exsd
index 0b1adee..3454e83 100644
--- a/bundles/org.eclipse.remote.console/schema/consoleToolbar.exsd
+++ b/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.]
+ <extension
+ point="org.eclipse.remote.console.toolbar">
+ <action
+ actionFactory="com.example.actions.MyActionFactory"
+ connectionType="org.eclipse.remote.serial.core.connectionType"
+ id="com.example.actions.MyAction">
+ </action>
+ </extension>
</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 <code>org.eclipse.remote.console.ConsoleAction</code>
+
+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>
diff --git a/bundles/org.eclipse.remote.console/src/org/eclipse/remote/console/actions/ConsoleAction.java b/bundles/org.eclipse.remote.console/src/org/eclipse/remote/console/actions/ConsoleAction.java
index 0b5d60c..2dadfc2 100644
--- a/bundles/org.eclipse.remote.console/src/org/eclipse/remote/console/actions/ConsoleAction.java
+++ b/bundles/org.eclipse.remote.console/src/org/eclipse/remote/console/actions/ConsoleAction.java
@@ -16,32 +16,96 @@
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) {
- setupAction(text, tooltip, imageRegistry.getDescriptor(hoverImage), imageRegistry.getDescriptor(enabledImage),
- imageRegistry.getDescriptor(disabledImage), enabled);
+ /**
+ * @param text
+ * the text for this action
+ * @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);
diff --git a/bundles/org.eclipse.remote.console/src/org/eclipse/remote/console/actions/IConsoleActionFactory.java b/bundles/org.eclipse.remote.console/src/org/eclipse/remote/console/actions/IConsoleActionFactory.java
index fff843a..7f935c3 100644
--- a/bundles/org.eclipse.remote.console/src/org/eclipse/remote/console/actions/IConsoleActionFactory.java
+++ b/bundles/org.eclipse.remote.console/src/org/eclipse/remote/console/actions/IConsoleActionFactory.java
@@ -16,5 +16,16 @@
* @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);
}
