javadoc

5 files changed, 80 insertions, 50 deletions

diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/link/LinkedModeUI.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/link/LinkedModeUI.java
index 89e8ca631fe..d1535e37d43 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/link/LinkedModeUI.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/link/LinkedModeUI.java
@@ -58,7 +58,7 @@ import org.eclipse.jface.text.source.IAnnotationModelExtension;
 import org.eclipse.jface.text.source.ISourceViewer;
 
 /**
- * The UI for linked mode. Detects events that influence behaviour of the linked mode
+ * The UI for linked mode. Detects events that influence behavior of the linked mode
  * UI and acts upon them.
  * <p>
  * <code>LinkedModeUI</code> relies on all added
@@ -66,6 +66,9 @@ import org.eclipse.jface.text.source.ISourceViewer;
  * <code>ITextViewer</code> that implement <code>ITextViewerExtension</code>,
  * and the documents being edited to implement <code>IDocumentExtension3</code>.
  * </p>
+ * <p>
+ * Clients may instantiate and extend this class.
+ * </p>
  * 
  * @since 3.0
  */
@@ -89,7 +92,10 @@ public class LinkedModeUI {
 	public static final Object CYCLE_WHEN_NO_PARENT= new Object();
 
 	/**
-	 * Listener that gets notified when the linked mode ui switches its focus position.
+	 * Listener that gets notified when the linked mode UI switches its focus position.
+	 * <p>
+	 * Clients may implement this interface.
+	 * </p>
 	 */
 	public static interface ILinkedModeUIFocusListener {
 		/**
@@ -125,7 +131,9 @@ public class LinkedModeUI {
 	/**
 	 * A link target consists of a viewer and gets notified if the linked mode UI on
 	 * it is being shown.
-	 * 
+	 * <p>
+	 * Clients may extend this class.
+	 * </p>
 	 * @since 3.0
 	 */
 	public static abstract class LinkedModeUITarget implements ILinkedModeUIFocusListener {
@@ -216,6 +224,9 @@ public class LinkedModeUI {
 
 	/**
 	 * Exit flags returned if a custom exit policy wants to exit linked mode.
+	 * <p>
+	 * Clients may instantiate this class.
+	 * </p>
 	 */
 	public static class ExitFlags {
 		/** The flags to return in the <code>leave</code> method. */
@@ -236,7 +247,10 @@ public class LinkedModeUI {
 
 	/**
 	 * An exit policy can be registered by a caller to get custom exit
-	 * behaviour.
+	 * behavior.
+	 * <p>
+	 * Clients may implement this interface.
+	 * </p>
 	 */
 	public interface IExitPolicy {
 		/**
@@ -543,39 +557,37 @@ public class LinkedModeUI {
 			
 		}
 	};
-	/** Whether this ui is in simple highlighting mode or not. */
+	/** Whether this UI is in simple highlighting mode or not. */
 	private boolean fSimple;
 
 	/**
-	 * Creates a new UI on the given model and the set of
-	 * viewers. The model must provide a tab stop sequence with a
-	 * non-empty list of tab stops.
+	 * Creates a new UI on the given model and the set of viewers. The model
+	 * must provide a tab stop sequence with a non-empty list of tab stops.
 	 * 
 	 * @param model the linked mode model
-	 * @param targets the non-empty list of targets upon which the linked mode ui
-	 *        should act
+	 * @param targets the non-empty list of targets upon which the linked mode
+	 *        UI should act
 	 */
 	public LinkedModeUI(LinkedModeModel model, LinkedModeUITarget[] targets) {
 		constructor(model, targets);
 	}
 
 	/**
-	 * Conveniance ctor for just one viewer.
+	 * Convenience constructor for just one viewer.
 	 * 
 	 * @param model the linked mode model
-	 * @param viewer the viewer upon which the linked mode ui
-	 *        should act
+	 * @param viewer the viewer upon which the linked mode UI should act
 	 */
 	public LinkedModeUI(LinkedModeModel model, ITextViewer viewer) {
 		constructor(model, new LinkedModeUITarget[]{new EmptyTarget(viewer)});
 	}
 
 	/**
-	 * Conveniance ctor for multiple viewers.
+	 * Convenience constructor for multiple viewers.
 	 * 
 	 * @param model the linked mode model
-	 * @param viewers the non-empty list of viewers upon which the linked mode ui
-	 *        should act
+	 * @param viewers the non-empty list of viewers upon which the linked mode
+	 *        UI should act
 	 */
 	public LinkedModeUI(LinkedModeModel model, ITextViewer[] viewers) {
 		LinkedModeUITarget[] array= new LinkedModeUITarget[viewers.length];
@@ -586,11 +598,10 @@ public class LinkedModeUI {
 	}
 
 	/**
-	 * Conveniance ctor for one target.
+	 * Convenience constructor for one target.
 	 * 
 	 * @param model the linked mode model
-	 * @param target the target upon which the linked mode ui
-	 *        should act
+	 * @param target the target upon which the linked mode UI should act
 	 */
 	public LinkedModeUI(LinkedModeModel model, LinkedModeUITarget target) {
 		constructor(model, new LinkedModeUITarget[]{target});
@@ -634,7 +645,7 @@ public class LinkedModeUI {
 	}
 
 	/**
-	 * Sets an <code>IExitPolicy</code> to customize the exit behaviour of
+	 * Sets an <code>IExitPolicy</code> to customize the exit behavior of
 	 * this linked mode UI.
 	 * 
 	 * @param policy the exit policy to use.
@@ -644,16 +655,18 @@ public class LinkedModeUI {
 	}
 
 	/**
-	 * Sets the exit position to move the caret to when linked mode mode is exited.
+	 * Sets the exit position to move the caret to when linked mode mode is
+	 * exited.
 	 * 
 	 * @param target the target where the exit position is located
 	 * @param offset the offset of the exit position
 	 * @param length the length of the exit position (in case there should be a
 	 *        selection)
-	 * @param sequence set to the tab stop position of the exit position, or 
-	 * 		  <code>LinkedPositionGroup.NO_STOP</code> if there should be no tab stop.
-	 * @throws BadLocationException if the position is not valid in the
-	 *         viewer's document
+	 * @param sequence set to the tab stop position of the exit position, or
+	 *        <code>LinkedPositionGroup.NO_STOP</code> if there should be no
+	 *        tab stop.
+	 * @throws BadLocationException if the position is not valid in the viewer's
+	 *         document
 	 */
 	public void setExitPosition(LinkedModeUITarget target, int offset, int length, int sequence) throws BadLocationException {
 		// remove any existing exit position
@@ -1120,8 +1133,6 @@ public class LinkedModeUI {
 			return new Region(fFramePosition.getOffset(), fFramePosition.getLength());
 	}
 
-	
-
 	private String getCategory() {
 		return toString();
 	}
@@ -1131,7 +1142,8 @@ public class LinkedModeUI {
 	 * info will be invoked on the current target's viewer whenever a position
 	 * is switched.
 	 * 
-	 * @param doContextInfo The doContextInfo to set.
+	 * @param doContextInfo <code>true</code> if context information should be
+	 *        displayed
 	 */
 	public void setDoContextInfo(boolean doContextInfo) {
 		fDoContextInfo= doContextInfo;
@@ -1139,9 +1151,10 @@ public class LinkedModeUI {
 	
 	/**
 	 * Sets the focus callback which will get informed when the focus of the 
-	 * linked mode ui changes.
+	 * linked mode UI changes.
 	 * <p>
-	 * If there is a listener installed already, it will be replaced.</p> 
+	 * If there is a listener installed already, it will be replaced.
+	 * </p>
 	 *  
 	 * @param listener the new listener, never <code>null</code>.
 	 */
@@ -1151,12 +1164,12 @@ public class LinkedModeUI {
 	}
 	
 	/**
-	 * Sets the "simple" mode of the receiver. A linked mode ui in simple mode 
+	 * Sets the "simple" mode of the receiver. A linked mode UI in simple mode 
 	 * merely draws the exit position, but not the target, focus, and slave
 	 * positions. Default is <code>false</code>. This method must be called
 	 * before it is entered.
 	 * 
-	 * @param simple <code>true</code> if the ui should be in simple mode.
+	 * @param simple <code>true</code> if the UI should be in simple mode.
 	 */
 	public void setSimpleMode(boolean simple) {
 		fSimple= simple;
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/link/LinkedPositionAnnotations.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/link/LinkedPositionAnnotations.java
index af2779586ae..30766fbced6 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/link/LinkedPositionAnnotations.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/link/LinkedPositionAnnotations.java
@@ -28,6 +28,8 @@ import org.eclipse.jface.text.source.Annotation;
 import org.eclipse.jface.text.source.AnnotationModel;
 
 /**
+ * Internal class.
+ * 
  * @since 3.0
  */
 final class LinkedPositionAnnotations extends AnnotationModel {
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/link/ProposalPosition.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/link/ProposalPosition.java
index d40448c5b8a..6f741b67d76 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/link/ProposalPosition.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/link/ProposalPosition.java
@@ -17,28 +17,41 @@ import org.eclipse.jface.text.contentassist.ICompletionProposal;
 
 /**
  * LinkedPosition with added completion proposals.
+ * <p>
+ * Clients may instantiate or extend this class.
+ * </p>
  * 
  * @since 3.0
  */
 public class ProposalPosition extends LinkedPosition {
 
 	/**
-	 * Da proposals
+	 * The proposals
 	 */
 	private ICompletionProposal[] fProposals;
 
 	/**
-	 * @param document
-	 * @param offset
-	 * @param length
-	 * @param sequence
-	 * @param proposals
+	 * Creates a new instance.
+	 * 
+	 * @param document the document
+	 * @param offset the offset of the position
+	 * @param length the length of the position
+	 * @param sequence the iteration sequence rank
+	 * @param proposals the proposals to be shown when entering this position
 	 */
 	public ProposalPosition(IDocument document, int offset, int length, int sequence, ICompletionProposal[] proposals) {
 		super(document, offset, length, sequence);
 		fProposals= proposals;
 	}
 	
+	/**
+	 * Creates a new instance, with no sequence number.
+	 * 
+	 * @param document the document
+	 * @param offset the offset of the position
+	 * @param length the length of the position
+	 * @param proposals the proposals to be shown when entering this position
+	 */
 	public ProposalPosition(IDocument document, int offset, int length, ICompletionProposal[] proposals) {
 		super(document, offset, length, LinkedPositionGroup.NO_STOP);
 		fProposals= proposals;
@@ -57,7 +70,10 @@ public class ProposalPosition extends LinkedPosition {
 	}
 
 	/**
-	 * @return an array of choices, including the initial one. Clients must not modify it.
+	 * Returns the proposals attached to this position.
+	 * 
+	 * @return an array of choices, including the initial one. Callers must not
+	 *         modify it.
 	 */
 	public ICompletionProposal[] getChoices() {
 		return fProposals;
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/link/TabStopIterator.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/link/TabStopIterator.java
index ed2d521faa3..060bc54d9ce 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/link/TabStopIterator.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/link/TabStopIterator.java
@@ -26,7 +26,9 @@ import org.eclipse.jface.text.link.LinkedPosition;
 /**
  * Iterator that leaps over the double occurrence of an element when switching from forward
  * to backward iteration that is shown by <code>ListIterator</code>.
- * 
+ * <p>
+ * Package private, only for use by LinkedModeUI.
+ * </p>
  * @since 3.0
  */
 class TabStopIterator {
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/link/package.html b/org.eclipse.jface.text/src/org/eclipse/jface/text/link/package.html
index c09d62d880b..153941b2c51 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/link/package.html
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/link/package.html
@@ -22,9 +22,9 @@ of one linked position will be reflected in the others.
 <h4>Classes</h4>
 <ul>
   <li><code>LinkedPositionGroup</code>: a set of linked positions. Add
-positions to a group using the <code>addPosition</code> and <code>createPosition</code>
-methods, which
-also allow to specify an iteration order. See <span
+positions to a group using the <code>addPosition</code> method. See <span
+ style="font-family: monospace;">LinkedPosition</span><code><span
+ style="font-family: helvetica,arial,sans-serif;"> and</span></code> <span
  style="font-family: monospace;">ProposalPosition</span><code><span
  style="font-family: helvetica,arial,sans-serif;"> </span></code><span
  style="font-family: helvetica,arial,sans-serif;">for a position type
@@ -54,7 +54,8 @@ mode (e.g. using Enter, or Tab from the last position when not
 cycling). Set <code>isTabStop</code> to <code>true</code> if tabbing
 should stop over when cycling.</li>
       <li><span style="font-weight: bold;">position listener</span>:
-you can register a position listener which will get notified whenever
+extending classes may register a position listener which will get
+notified whenever
 the focus position changes. An example is <span
  style="font-family: monospace;">org.eclipse.ui.texteditor.link.EditorLinkedModeUI.EditorHistoryUpdater</span>
 which will store the edit location in the editor navigation history.<br>
@@ -64,11 +65,7 @@ which will store the edit location in the editor navigation history.<br>
 .
 </ul>
 <h4>Example</h4>
-<pre>	IDocument doc1, doc2;<br>	ITextViewer viewer1, viewer2;<br>	<br>	/* create groups - this step is independent of the linked mode */<br>	LinkedPositionGroup group1= new LinkedPositionGroup();<br>	group1.addPosition(new LinkedPosition(doc1, 3, 4));<br>	group1.addPosition(new LinkedPosition(doc1, 7, 8));<br>	<br>	LinkedPositionGroup group2= new LinkedPositionGroup();<br>	group2.addPosition(new LinkedPosition(doc1, 15, 25));<br>	group2.addPosition(new LinkedPosition(doc2, 0, 10));<br>	<br>	/* set up linked mode */<br>	LinkedModeModel model= new LinkedModeModel();<br>	model.addGroup(group1);<br>	model.addGroup(group2);<br>	model.forceInstall();<br>	<br>	/* create UI */<br>	LinkedModeUI ui= new LinkedModeUI(model, new ITextViewer[] { viewer1, viewer2 });<br>	ui.enter();<br></pre>
-<h4>Todo</h4>
-<ul>
-  <li>handle lazy computation of per-group proposals using a <code>IContentAssistProcessor</code>
-(see LinkedPositionGroup, ProposalPosition) .</li>
-</ul>
+<pre>	IDocument doc1, doc2;<br>	ITextViewer viewer1, viewer2;<br>	<br>	/* create groups - this step is independent of the linked mode */<br>	LinkedPositionGroup group1= new LinkedPositionGroup();<br>	group1.addPosition(new LinkedPosition(doc1, 3, 4));<br>	group1.addPosition(new LinkedPosition(doc1, 7, 8));<br>	<br>	LinkedPositionGroup group2= new LinkedPositionGroup();<br>	group2.addPosition(new LinkedPosition(doc1, 15, 25));<br>	group2.addPosition(new LinkedPosition(doc2, 0, 10));<br>	<br>	/* set up linked mode */<br>	LinkedModeModel model= new LinkedModeModel();<br>	model.addGroup(group1);<br>	model.addGroup(group2);<br>	model.forceInstall();<br>	<br>	/* create UI */<br>	LinkedModeUI ui= new LinkedModeUI(model, new ITextViewer[] { viewer1, viewer2 });<br>	ui.enter();<span
+ style="font-family: sans-serif;"><br><br></span></pre>
 </body>
 </html>