cleanups and doc additions
diff --git a/org.eclipse.wst.common.snippets/src/org/eclipse/wst/common/snippets/core/ISnippetItem.java b/org.eclipse.wst.common.snippets/src/org/eclipse/wst/common/snippets/core/ISnippetItem.java
index 15ecfa9..d8801f0 100644
--- a/org.eclipse.wst.common.snippets/src/org/eclipse/wst/common/snippets/core/ISnippetItem.java
+++ b/org.eclipse.wst.common.snippets/src/org/eclipse/wst/common/snippets/core/ISnippetItem.java
@@ -9,14 +9,14 @@
* IBM Corporation - initial API and implementation
*******************************************************************************/
-
package org.eclipse.wst.common.snippets.core;
import org.eclipse.wst.common.snippets.internal.ISnippetCategory;
import org.eclipse.wst.common.snippets.internal.ISnippetVariable;
-
/**
+ * A snippet item is the actual object draggable from the Snippets view.
+ *
* This interface is not meant to be implemented by clients.
*/
public interface ISnippetItem extends ISnippetsEntry {
@@ -49,7 +49,8 @@
String getClassName();
/**
- * @return the content string for this item
+ * @return the content string for this item; the text inserted may not be
+ * identical
*/
String getContentString();
@@ -84,6 +85,7 @@
/**
* @param the name of the category holding this item. This is a handle
* only method; the category need not exist yet.
+ * @deprecated - should not be changeable
*/
void setCategoryName(String name);
@@ -96,6 +98,7 @@
/**
* @param the new content string for this item
+ * @deprecated - should not be changeable
*/
void setContentString(String content);
diff --git a/org.eclipse.wst.common.snippets/src/org/eclipse/wst/common/snippets/core/ISnippetsEntry.java b/org.eclipse.wst.common.snippets/src/org/eclipse/wst/common/snippets/core/ISnippetsEntry.java
index cced4ee..f1f7c6e 100644
--- a/org.eclipse.wst.common.snippets/src/org/eclipse/wst/common/snippets/core/ISnippetsEntry.java
+++ b/org.eclipse.wst.common.snippets/src/org/eclipse/wst/common/snippets/core/ISnippetsEntry.java
@@ -12,48 +12,137 @@
package org.eclipse.wst.common.snippets.core;
-
/**
+ * A Snippets Entry is an abstract notion encapsulating the values used to
+ * represent Snippet Items and Containers. No object implements only this
+ * interface.
+ *
* This interface is not meant to be implemented by clients.
*/
+
public interface ISnippetsEntry {
+
+ /**
+ * Denotes that this entry was contributed by a plug-in
+ */
final String SNIPPET_SOURCE_PLUGINS = "PLUGINS"; //$NON-NLS-1$
+
+ /**
+ * Denotes that this entry was created by the user
+ */
final String SNIPPET_SOURCE_USER = "USER"; //$NON-NLS-1$
+
+ /**
+ * Denotes that this entry was discovered within the workspace
+ * @deprecated
+ */
final String SNIPPET_SOURCE_WORKSPACE = "WORKSPACE"; //$NON-NLS-1$
+ /**
+ * @return the (lengthy) text description shown to the user for this entry
+ */
String getDescription();
+ /**
+ * @return the filters for which this entry will be shown (when filtering
+ * is enabled)
+ */
String[] getFilters();
+ /**
+ * @return the path to the icon image for this entry, relative to the
+ * entry's contributing plugin installation path or relative to
+ * the Snippets plugin's installation path
+ */
String getIconName();
+ /**
+ * @return a unique ID for this entry
+ */
String getId();
+ /**
+ * @return the (short) string shown to the user for this entry
+ */
String getLabel();
+ /**
+ * @return the path to a large icon image for this entry, relative to the
+ * entry's contributing plugin installation path or relative to
+ * the Snippets plugin's installation path, or null if one is not
+ * specified.
+ */
String getLargeIconName();
+ /**
+ * @return the object defining where this entry originated from. Valid
+ * values are instances of CategoryFileInfo and PluginRecord.
+ */
Object getSourceDescriptor();
+ /**
+ * @return the type of the source descriptor. Valid values are
+ * SNIPPET_SOURCE_PLUGINS, SNIPPET_SOURCE_USER, and
+ * SNIPPET_SOURCE_WORKSPACE.
+ */
Object getSourceType();
+ /**
+ * @return whether this entry is currently visible to the user or not
+ */
boolean isVisible();
+ /**
+ * @param description
+ * @deprecated
+ */
void setDescription(String description);
+ /**
+ * @param filters
+ * @deprecated
+ */
void setFilters(String[] filters);
+ /**
+ * @param icon
+ * @deprecated
+ */
void setIconName(String icon);
+ /**
+ * @param id
+ * @deprecated
+ */
void setId(String id);
+ /**
+ * @param label the (short) string shown to the user for this entry
+ * @deprecated
+ */
void setLabel(String label);
+ /**
+ * @param icon
+ * @deprecated
+ */
void setLargeIconName(String icon);
+ /**
+ * @param descriptor
+ * @deprecated
+ */
void setSourceDescriptor(Object descriptor);
+ /**
+ * @param type
+ * @deprecated
+ */
void setSourceType(Object type);
+ /**
+ * @param visible
+ * @deprecated
+ */
void setVisible(boolean visible);
}
\ No newline at end of file
diff --git a/org.eclipse.wst.common.snippets/src/org/eclipse/wst/common/snippets/core/ISnippetsInsertion.java b/org.eclipse.wst.common.snippets/src/org/eclipse/wst/common/snippets/core/ISnippetsInsertion.java
index 2e21e23..8400dd2 100644
--- a/org.eclipse.wst.common.snippets/src/org/eclipse/wst/common/snippets/core/ISnippetsInsertion.java
+++ b/org.eclipse.wst.common.snippets/src/org/eclipse/wst/common/snippets/core/ISnippetsInsertion.java
@@ -17,9 +17,9 @@
import org.eclipse.ui.IEditorPart;
/**
- * The generic insertion interface. Implementors are responsible for
- * supporting the drag-and-drop mechanism and inserting the snippet's text
- * into an editor part.
+ * An insertion class is responsible for inserting a snippet item's contents
+ * into editors. Implementors are responsible for supporting the drag-and-drop
+ * mechanism and inserting the snippet's text into a given editor part.
*/
public interface ISnippetsInsertion {
diff --git a/org.eclipse.wst.common.snippets/src/org/eclipse/wst/common/snippets/editors/ISnippetEditor.java b/org.eclipse.wst.common.snippets/src/org/eclipse/wst/common/snippets/editors/ISnippetEditor.java
index 6b8e4c9..eead61c 100644
--- a/org.eclipse.wst.common.snippets/src/org/eclipse/wst/common/snippets/editors/ISnippetEditor.java
+++ b/org.eclipse.wst.common.snippets/src/org/eclipse/wst/common/snippets/editors/ISnippetEditor.java
@@ -9,7 +9,6 @@
* IBM Corporation - initial API and implementation
*******************************************************************************/
-
package org.eclipse.wst.common.snippets.editors;
import org.eclipse.swt.events.ModifyListener;
@@ -17,10 +16,17 @@
import org.eclipse.swt.widgets.Control;
import org.eclipse.wst.common.snippets.core.ISnippetItem;
-
-
+/**
+ * A snippet editor is responsible for creating the interface from which a
+ * user modifies a snippet item or category.
+ */
public interface ISnippetEditor {
+ /**
+ * Adds a modify listener to this editor. Typically the UI surrounding
+ * this editor will listen for modifications.
+ * @param listener the to be added
+ */
void addModifyListener(ModifyListener listener);
/**
@@ -33,6 +39,11 @@
*/
ISnippetItem getItem();
+ /**
+ * Remove a modify listener from this editor. Typically the UI surrounding
+ * this editor will listen for modifications.
+ * @param listener the to be added
+ */
void removeModifyListener(ModifyListener listener);
/**
@@ -45,5 +56,4 @@
* dialog's controls have been changed or it is being closed.
*/
void updateItem();
-
}
\ No newline at end of file
diff --git a/org.eclipse.wst.common.snippets/src/org/eclipse/wst/common/snippets/editors/VariableItemEditor.java b/org.eclipse.wst.common.snippets/src/org/eclipse/wst/common/snippets/editors/VariableItemEditor.java
index 0ff43de..57e2574 100644
--- a/org.eclipse.wst.common.snippets/src/org/eclipse/wst/common/snippets/editors/VariableItemEditor.java
+++ b/org.eclipse.wst.common.snippets/src/org/eclipse/wst/common/snippets/editors/VariableItemEditor.java
@@ -64,10 +64,12 @@
import org.eclipse.wst.sse.core.util.StringUtils;
import org.eclipse.wst.sse.ui.util.Sorter;
+/**
+ * A snippet item editor that can define snippet variables
+ */
public class VariableItemEditor implements ISnippetEditor {
- public static class CompletionProposalSorter extends Sorter {
-
- protected Collator collator = Collator.getInstance();
+ private static class CompletionProposalSorter extends Sorter {
+ Collator collator = Collator.getInstance();
public boolean compare(Object elementOne, Object elementTwo) {
/**
@@ -83,7 +85,6 @@
}
private class ItemEditorSourceViewerConfiguration extends SourceViewerConfiguration {
-
private IContentAssistProcessor fProcessor = null;
public ItemEditorSourceViewerConfiguration() {
@@ -181,7 +182,6 @@
* @see SourceViewerConfiguration#getContentAssistant(ISourceViewer)
*/
public IContentAssistant getContentAssistant(ISourceViewer sourceViewer) {
-
ContentAssistant assistant = new ContentAssistant();
assistant.setContentAssistProcessor(fProcessor, IDocument.DEFAULT_CONTENT_TYPE);
@@ -214,9 +214,6 @@
getListeners().add(listener);
}
- /**
- * @see ISnippetEditor#createContents(Composite)
- */
public Control createContents(Composite parent) {
// create the contents of the variable editing dialog
@@ -405,14 +402,13 @@
}
});
- // Add the "Insert Variable Placeholder" button to invoke content
- // assist
- //
- // Derived from the JDT template editor, I'm not sure I like this idea
- // as
- // it's mostly a crutch for not making content assist obviously
- // available
- // in the source viewer
+ /*
+ * Add the "Insert Variable Placeholder" button to invoke content
+ * assist like the JDT Template editor.
+ *
+ * I'm not sure I like this idea as it's mostly a crutch for not
+ * making content assist obviously available in the source viewer.
+ */
final Button insertVariableButton = new Button(parent, SWT.PUSH);
insertVariableButton.setText(SnippetsPlugin.getResourceString("%Insert_Variable_17")); //$NON-NLS-1$
insertVariableButton.setLayoutData(new GridData(GridData.HORIZONTAL_ALIGN_BEGINNING | GridData.VERTICAL_ALIGN_BEGINNING));
diff --git a/org.eclipse.wst.common.snippets/src/org/eclipse/wst/common/snippets/insertions/AbstractInsertion.java b/org.eclipse.wst.common.snippets/src/org/eclipse/wst/common/snippets/insertions/AbstractInsertion.java
index 9a6bd91..18d096d 100644
--- a/org.eclipse.wst.common.snippets/src/org/eclipse/wst/common/snippets/insertions/AbstractInsertion.java
+++ b/org.eclipse.wst.common.snippets/src/org/eclipse/wst/common/snippets/insertions/AbstractInsertion.java
@@ -80,7 +80,7 @@
*
* @param host a shell from which UI elements may be opened to help
* determine what String to return
- *
+ *
* @return the String to be inserted
*/
public String getInsertString(Shell host) {
@@ -97,9 +97,6 @@
return fItem;
}
- /* (non-Javadoc)
- * @see org.eclipse.wst.common.snippets.core.ISnippetsInsertion#getTransfers()
- */
public Transfer[] getTransfers() {
if (supportedTransfers == null)
supportedTransfers = createTransfers();
@@ -153,5 +150,4 @@
public void setItem(ISnippetItem item) {
this.fItem = item;
}
-
}
\ No newline at end of file
diff --git a/org.eclipse.wst.common.snippets/src/org/eclipse/wst/common/snippets/insertions/VariableInsertion.java b/org.eclipse.wst.common.snippets/src/org/eclipse/wst/common/snippets/insertions/VariableInsertion.java
index 2e93c21..c1ef007 100644
--- a/org.eclipse.wst.common.snippets/src/org/eclipse/wst/common/snippets/insertions/VariableInsertion.java
+++ b/org.eclipse.wst.common.snippets/src/org/eclipse/wst/common/snippets/insertions/VariableInsertion.java
@@ -34,9 +34,16 @@
import org.eclipse.wst.sse.core.util.StringUtils;
import org.eclipse.wst.sse.ui.extension.IExtendedSimpleEditor;
+/**
+ * An insertion implementation that supports ISnippetVariables. The content
+ * string of the item can contain markers, in the form ${+variable+}, that
+ * will be replaced with user-supplied values at insertion time.
+ */
public class VariableInsertion extends AbstractInsertion {
-
+ /**
+ * Default public constructor
+ */
public VariableInsertion() {
super();
}
@@ -46,10 +53,12 @@
}
/**
- *
- * @param part
- * @param editor
- * @throws BadLocationException
+ * Performs the insertion
+ * @param part the part into which to insert
+ * @param editor an implementor of IExtendedSimpleEditor to facilitate
+ * manipulation of the document
+ * @throws BadLocationException if the editor's selected range is invalid
+ * in the simple editor's document
*/
protected void doInsert(IEditorPart part, IExtendedSimpleEditor editor) throws BadLocationException {
String replacement = getInsertString(part.getEditorSite().getShell());
