Javadoc updates

11 files changed, 134 insertions, 71 deletions

diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/AbstractReconcileStep.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/AbstractReconcileStep.java
index 52483b8824f..cf95717bb93 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/AbstractReconcileStep.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/AbstractReconcileStep.java
@@ -113,10 +113,24 @@ public abstract class AbstractReconcileStep implements IReconcileStep {
 	 */
 	abstract protected IReconcileResult[] reconcileModel(DirtyRegion dirtyRegion, IRegion subRegion);
 
+	/**
+	 * Adapts the given an array with reconcile results to
+	 * this step's input model and returns it. 
+	 * 
+	 * @param inputResults an array with reconcile results 
+	 * @return an array with the reconcile results adapted to the input model
+	 */
 	protected IReconcileResult[] convertToInputModel(IReconcileResult[] inputResults) {
 		return inputResults;
 	}
 	
+	/**
+	 * Merges the two reconcile result arrays.
+	 * 
+	 * @param results1 an array with reconcile results
+	 * @param results2 an array with reconcile results
+	 * @return an array with the merged reconcile results
+	 */
 	private IReconcileResult[] merge(IReconcileResult[] results1, IReconcileResult[] results2) {
 		if (results1 == null)
 			return results2;
@@ -156,9 +170,19 @@ public abstract class AbstractReconcileStep implements IReconcileStep {
 			fNextStep.setInputModel(getModel());
 	}
 
+	/**
+	 * Returns the reconcilable input model.
+	 * 
+	 * @return the reconcilable input model.
+	 */
 	public IReconcilableModel getInputModel() {
 		return fInputModel;
 	}
 	
+	/**
+	 * Returns the reconcilable model.
+	 * 
+	 * @return the reconcilable model
+	 */
 	abstract public IReconcilableModel getModel();
 }
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/AbstractReconciler.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/AbstractReconciler.java
index 87fff58cb21..fa7a39a29c1 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/AbstractReconciler.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/AbstractReconciler.java
@@ -22,24 +22,26 @@ import org.eclipse.jface.text.ITextViewer;
 
 
 /**
- * Abstract implementation of <code>IReconciler</code>. The reconciler
+ * Abstract implementation of {@link IReconciler}. The reconciler
  * listens to input document changes as well as changes of
  * the input document of the text viewer it is installed on. Depending on 
  * its configuration it manages the received change notifications in a 
- * queue folding neighboring or overlapping changes together.  The reconciler
+ * queue folding neighboring or overlapping changes together. The reconciler
  * processes the dirty regions as a background activity after having waited for further
- * changes for the configured duration of time. A reconciler is started using its
- * <code>install</code> method.  As a first step <code>initialProcess</code> is
+ * changes for the configured duration of time. A reconciler is started using the
+ * {@link #install(ITextViewer)} method.  As a first step {@link #initialProcess()} is
  * executed in the background. Then, the reconciling thread waits for changes that
- * need to be reconciled. A reconciler can be resumed by calling <code>forceReconciling</code>
+ * need to be reconciled. A reconciler can be resumed by calling {@link #forceReconciling()}
  * independent from the existence of actual changes. This mechanism is for subclasses only.
- * It is the clients responsibility to stop a reconciler using its <code>uninstall</code>
- * method. Unstopped reconcilers do not free their resources.<p>
+ * It is the clients responsibility to stop a reconciler using its {@link #uninstall()}
+ * method. Unstopped reconcilers do not free their resources.
+ * <p>
  * It is subclass responsibility to specify how dirty regions are processed.
- *
- * @see IDocumentListener
- * @see ITextInputListener
- * @see DirtyRegion
+ * </p>
+ * 
+ * @see org.eclipse.jface.text.IDocumentListener
+ * @see org.eclipse.jface.text.ITextInputListener
+ * @see org.eclipse.jface.text.reconciler.DirtyRegion
  * @since 2.0
  */
 abstract public class AbstractReconciler implements IReconciler {
@@ -151,8 +153,10 @@ abstract public class AbstractReconciler implements IReconciler {
 		/**
 		 * The background activity. Waits until there is something in the
 		 * queue managing the changes that have been applied to the text viewer.
-		 * Removes the first change from the queue and process it.<p>
-		 * Calls <code>initialProcess</code> on entrance.
+		 * Removes the first change from the queue and process it.
+		 * <p>
+		 * Calls {@link AbstractReconciler#initialProcess()} on entrance.
+		 * </p>
 		 */
 		public void run() {
 			
@@ -293,20 +297,20 @@ abstract public class AbstractReconciler implements IReconciler {
 		}			
 	}
 	
-	/** Queue to manage the changes applied to the text viewer */
+	/** Queue to manage the changes applied to the text viewer. */
 	private DirtyRegionQueue fDirtyRegionQueue;
-	/** The background thread */
+	/** The background thread. */
 	private BackgroundThread fThread;
-	/** Internal document and text input listener */
+	/** Internal document and text input listener. */
 	private Listener fListener;
-	/** The background thread delay */
+	/** The background thread delay. */
 	private int fDelay= 500;
 	/** Are there incremental reconciling strategies? */
 	private boolean fIsIncrementalReconciler= true;
-	/** The progress monitor used by this reconciler */
+	/** The progress monitor used by this reconciler. */
 	private IProgressMonitor fProgressMonitor;
 
-	/** The text viewer's document */
+	/** The text viewer's document. */
 	private IDocument fDocument;
 	/** The text viewer */
 	private ITextViewer fViewer;
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/DirtyRegion.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/DirtyRegion.java
index f90261f9794..92ad6623867 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/DirtyRegion.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/DirtyRegion.java
@@ -27,13 +27,13 @@ public class DirtyRegion implements ITypedRegion {
 	 */
 	final static public String REMOVE= "__remove"; //$NON-NLS-1$
 	
-	/** The region's offset */
+	/** The region's offset. */
 	private int fOffset;
-	/** The region's length */
+	/** The region's length. */
 	private int fLength;
-	/** Indicates the type of the applied change */
+	/** Indicates the type of the applied change. */
 	private String fType;
-	/** The text which has been inserted */
+	/** The text which has been inserted. */
 	private String fText;
 
 	/**
@@ -41,7 +41,7 @@ public class DirtyRegion implements ITypedRegion {
 	 * 
 	 * @param offset the offset within the document where the change occurred
 	 * @param length the length of the text within the document that changed
-	 * @param type the type of change that this region represents: <code>INSERT</code> or <code>REMOVE</code>
+	 * @param type the type of change that this region represents: {@link #INSERT} {@link #REMOVE}
 	 * @param text the substitution text
 	 */
 	public DirtyRegion(int offset, int length, String type, String text) {
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/DirtyRegionQueue.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/DirtyRegionQueue.java
index 6428d6d323c..322be422c93 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/DirtyRegionQueue.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/DirtyRegionQueue.java
@@ -15,8 +15,9 @@ import java.util.ArrayList;
 
 
 /**
- * Queue used by {@link org.eclipse.jface.text.reconciler.Reconciler} to manage dirty regions. When a dirty region
- * is inserted into the queue, the queue tries to fold it into the neighboring dirty region.
+ * Queue used by {@link org.eclipse.jface.text.reconciler.Reconciler} to manage
+ * dirty regions. When a dirty region is inserted into the queue, the queue tries
+ * to fold it into the neighboring dirty region.
  *
  * @see org.eclipse.jface.text.reconciler.Reconciler
  * @see org.eclipse.jface.text.reconciler.DirtyRegion
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/IReconcileStep.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/IReconcileStep.java
index 13d1e53b77d..31d551cd3c3 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/IReconcileStep.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/IReconcileStep.java
@@ -17,10 +17,10 @@ import org.eclipse.jface.text.reconciler.DirtyRegion;
 
 
 /**
- * A reconcile step is one of several steps of a reconcile
- * strategy that consists of several steps.
+ * A reconcile step is one of several steps of a
+ * {@linkplain org.eclipse.jface.text.reconciler.IReconcilingStrategy reconcile strategy}
+ * that consists of several steps.
  * 
- * @see org.eclipse.jface.text.reconciler.IReconcilingStrategy 
  * @since 3.0
  */
 public interface IReconcileStep {
@@ -28,14 +28,14 @@ public interface IReconcileStep {
 	/**
 	 * Returns whether this is the last reconcile step or not.
 	 * 
-	 * @return <code>true</code> if this is the last reconcile step
+	 * @return <code>true</code> iff this is the last reconcile step
 	 */
 	boolean isLastStep();
 
 	/**
 	 * Returns whether this is the first reconcile step or not.
 	 * 
-	 * @return <code>true</code> if this is the last reconcile step
+	 * @return <code>true</code> iff this is the first reconcile step
 	 */
 	boolean isFirstStep();
 
@@ -46,7 +46,7 @@ public interface IReconcileStep {
 	 * </p>
 	 * 
 	 * @param step the previous step
-	 * @throws org.eclipse.jface.text.Assert#AssertionFailedException if called more than once
+	 * @throws RuntimeException if called more than once
 	 */
 	void setPreviousStep(IReconcileStep step);
 
@@ -55,7 +55,7 @@ public interface IReconcileStep {
 	 * As a dirty region might span multiple content types, the segment of the
 	 * dirty region which should be investigated is also provided to this 
 	 * reconciling strategy. The given regions refer to the document passed into
-	 * the most recent call of <code>setDocument</code>.
+	 * the most recent call of {@link IReconcilingStrategy#setDocument(org.eclipse.jface.text.IDocument)}.
 	 *
 	 * @param dirtyRegion the document region which has been changed
 	 * @param subRegion the sub region in the dirty region which should be reconciled
@@ -66,7 +66,7 @@ public interface IReconcileStep {
 	/**
 	 * Activates non-incremental reconciling. The reconciling strategy is just told
 	 * that there are changes and that it should reconcile the given partition of the
-	 * document most recently passed into <code>setDocument</code>.
+	 * document most recently passed into {@link IReconcilingStrategy#setDocument(org.eclipse.jface.text.IDocument)}.
 	 *
 	 * @param partition the document partition to be reconciled
 	 * @return an array with reconcile results 
@@ -74,7 +74,7 @@ public interface IReconcileStep {
 	IReconcileResult[] reconcile(IRegion partition);
 
 	/**
-	 * Sets the progress monitor to this reconcile step.
+	 * Sets the progress monitor for this reconcile step.
 	 * 
 	 * @param monitor the progress monitor to be used
 	 */
@@ -83,7 +83,7 @@ public interface IReconcileStep {
 	/**
 	 * Returns the progress monitor used to report progress.
 	 *
-	 * @return a progress monitor or null if no progress monitor is provided
+	 * @return a progress monitor or <code>null</code> if no progress monitor is available
 	 */
 	public IProgressMonitor getProgressMonitor();
 
@@ -91,10 +91,10 @@ public interface IReconcileStep {
 	 * Tells this reconcile step on which model it will
 	 * work. This method will be called before any other method 
 	 * and can be called multiple times. The regions passed to the
-	 * other methods always refer to the most recent document 
+	 * other methods always refer to the most recent model 
 	 * passed into this method.
 	 *
-	 * @param inputModel the model on which this strategy will work
+	 * @param inputModel the model on which this step will work
 	 */
 	void setInputModel(IReconcilableModel inputModel);
 }
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/IReconciler.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/IReconciler.java
index f010f40d6cd..c2440805dc2 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/IReconciler.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/IReconciler.java
@@ -16,16 +16,31 @@ import org.eclipse.jface.text.ITextViewer;
 /**
  * An <code>IReconciler</code> defines and maintains a model of the content
  * of the text  viewer's document in the presence of changes applied to this 
- * document. An <code>IReconciler</code> is a <code>ITextViewer</code> add-on.<p>
+ * document. An <code>IReconciler</code> is a {@link org.eclipse.jface.text.ITextViewer} add-on.
+ * <p>
  * Reconcilers are assumed to be asynchronous, i.e. they allow a certain 
  * temporal window of inconsistency between the document and the model of
- * the content of this document. <p>
- * Reconcilers have a list of  <code>IReconcilingStrategy</code> objects 
- * each of which is registered for a  particular document content type. 
+ * the content of this document.
+ * </p>
+ * <p>
+ * Reconcilers have a list of {@link org.eclipse.jface.text.reconciler.IReconcilingStrategy} 
+ * objects each of which is registered for a  particular document content type.
  * The reconciler uses the strategy objects to react on the changes applied
- * to the text viewer's document.<p>
+ * to the text viewer's document.
+ *</p>
+ * <p>
+ * In order to provide backward compatibility for clients of <code>IReconciler</code>, extension
+ * interfaces are used to provide a means of evolution. The following extension interfaces exist:
+ * <ul>
+ * <li>{@link org.eclipse.jface.text.reconciler.IReconcilerExtension} since version 3.0 introducing 
+ *		the ability to be aware of documents with multiple partitions.</li>
+ * </ul>
+ * </p>
+ * <p>
  * The interface can be implemented by clients. By default, clients use
- * <code>Reconciler</code> as the standard implementer of this interface. 
+ * {@link org.eclipse.jface.text.reconciler.Reconciler} as the standard
+ * implementer of this interface. 
+ * </p>
  *
  * @see ITextViewer
  * @see IReconcilingStrategy 
@@ -34,7 +49,7 @@ public interface IReconciler {
 		
 	/**
 	 * Installs the reconciler on the given text viewer. After this method has been
-	 * finished, the reconciler is operational. I.e., it works without requesting 
+	 * finished, the reconciler is operational, i.e., it works without requesting 
 	 * further client actions until <code>uninstall</code> is called.
 	 * 
 	 * @param textViewer the viewer on which the reconciler is installed
@@ -42,8 +57,8 @@ public interface IReconciler {
 	void install(ITextViewer textViewer);
 	
 	/**
-	 * Removes the reconciler from the text viewer it has previously been
-	 * installed on. 
+	 * Removes the reconciler from the text viewer it has 
+	 * previously been installed on. 
 	 */
 	void uninstall();
 	
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/IReconcilerExtension.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/IReconcilerExtension.java
index 21b3037efb2..317b9b70f53 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/IReconcilerExtension.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/IReconcilerExtension.java
@@ -12,8 +12,8 @@ package org.eclipse.jface.text.reconciler;
 
 
 /**
- * Extension interface for <code>IReconciler</code>.
- * Updates the reconciler to be aware of documents with multiple partitions.
+ * Extends {@link org.eclipse.jface.text.reconciler.IReconciler} with 
+ * the ability to be aware of documents with multiple partitions.
  * 
  * @since 3.0
  */
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/IReconcilingStrategy.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/IReconcilingStrategy.java
index 2d6b51e24e7..8f1de7fae84 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/IReconcilingStrategy.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/IReconcilingStrategy.java
@@ -17,10 +17,27 @@ import org.eclipse.jface.text.IRegion;
 /**
  * A reconciling strategy is used by an reconciler to reconcile a model
  * based on text of a particular content type. It provides methods for 
- * incremental as well as non-incremental reconciling.<p>
+ * incremental as well as non-incremental reconciling.
+ * <p>
+ * In order to provide backward compatibility for clients of <code>IReconcilingStrategy</code>, extension
+ * interfaces are used to provide a means of evolution. The following extension interfaces exist:
+ * <ul>
+ * <li>{@link org.eclipse.jface.text.reconciler.IReconcilingStrategyExtension} since version 2.0 introducing 
+ *		the following functions:
+ *			<ul>
+ *				<li>usage of a progress monitor</li>
+ *				<li>initial reconciling step: if a reconciler runs as periodic activity in the background, this
+ *					methods offers the reconciler a chance for initializing its strategies and achieving a 
+ *					reconciled state before the periodic activity starts.</li>
+ *			</ul>
+ * </li>
+ * </ul>
+ * </p>
+ * <p>
  * This interface must be implemented by clients. Implementers should be
  * registered with a reconciler in order get involved in the reconciling 
  * process.
+ * </p>
  */
 public interface IReconcilingStrategy {
 	
@@ -40,7 +57,7 @@ public interface IReconcilingStrategy {
 	 * As a dirty region might span multiple content types, the segment of the
 	 * dirty region which should be investigated is also provided to this 
 	 * reconciling strategy. The given regions refer to the document passed into
-	 * the most recent call of <code>setDocument</code>.
+	 * the most recent call of {@link #setDocument(IDocument)}.
 	 *
 	 * @param dirtyRegion the document region which has been changed
 	 * @param subRegion the sub region in the dirty region which should be reconciled 
@@ -50,7 +67,7 @@ public interface IReconcilingStrategy {
 	/**
 	 * Activates non-incremental reconciling. The reconciling strategy is just told
 	 * that there are changes and that it should reconcile the given partition of the
-	 * document most recently passed into <code>setDocument</code>.
+	 * document most recently passed into {@link #setDocument(IDocument)}.
 	 *
 	 * @param partition the document partition to be reconciled
 	 */
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/IReconcilingStrategyExtension.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/IReconcilingStrategyExtension.java
index 33b1c100bda..1bbbde30f87 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/IReconcilingStrategyExtension.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/IReconcilingStrategyExtension.java
@@ -14,13 +14,13 @@ import org.eclipse.core.runtime.IProgressMonitor;
 
  
 /**
- * Extension interface for <code>IReconcilingStrategy</code>.
- * The new functions are:
+ * Extends {@link org.eclipse.jface.text.reconciler.IReconcilingStrategy} 
+ * with the following functions:
  * <ul>
- * <li> usage of a progress monitor
- * <li> initial reconciling step: If a reconciler runs as periodic activity in the background, this
+ * 	<li>usage of a progress monitor</li>
+ * 	<li>initial reconciling step: if a reconciler runs as periodic activity in the background, this
  * 		methods offers the reconciler a chance for initializing its strategies and achieving a 
- * 		reconciled state before the periodic activity starts.
+ * 		reconciled state before the periodic activity starts.</li>
  * </ul>
  * 
  * @since 2.0
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/MonoReconciler.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/MonoReconciler.java
index f82135457e5..058e82ce256 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/MonoReconciler.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/MonoReconciler.java
@@ -18,22 +18,23 @@ import org.eclipse.jface.text.Region;
 
 
 /**
- * Standard implementation of <code>IReconciler</code>. The reconciler
- * is configured with a single <code>IReconcilingStrategy</code> that is
- * used independently from where a dirty region is located in the reconciler's
- * document. <p>
+ * Standard implementation of {@link org.eclipse.jface.text.reconciler.IReconciler}.
+ * The reconciler is configured with a single {@linkplain org.eclipse.jface.text.reconciler.IReconcilingStrategy reconciling strategy}
+ * that is used independently from where a dirty region is located in the reconciler's
+ * document.
+ * <p>
  * Usually, clients instantiate this class and configure it before using it.
+ * </p>
  *
- * @see IReconciler
  * @see org.eclipse.jface.text.IDocumentListener
  * @see org.eclipse.jface.text.ITextInputListener
- * @see DirtyRegion
+ * @see org.eclipse.jface.text.reconciler.DirtyRegion
  * @since 2.0
  */
 public class MonoReconciler extends AbstractReconciler {
 	
 	
-	/** The reconciling strategy */
+	/** The reconciling strategy. */
 	private IReconcilingStrategy fStrategy;
 	
 	
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/Reconciler.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/Reconciler.java
index 3a4cc8ef2c4..72aa911d2bf 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/Reconciler.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/Reconciler.java
@@ -28,19 +28,20 @@ import org.eclipse.jface.text.TypedRegion;
 
 
 /**
- * Standard implementation of <code>IReconciler</code>. The reconciler
- * is configured with a set of reconciling strategies each of which is
- * responsible for a particular content type. <p>
+ * Standard implementation of {@link org.eclipse.jface.text.reconciler.IReconciler}.
+ * The reconciler is configured with a set of {@linkplain org.eclipse.jface.text.reconciler.IReconcilingStrategy reconciling strategies}
+ * each of which is responsible for a particular content type.
+ * <p>
  * Usually, clients instantiate this class and configure it before using it.
+ * </p>
  *
- * @see IReconciler
  * @see org.eclipse.jface.text.IDocumentListener
  * @see org.eclipse.jface.text.ITextInputListener
- * @see DirtyRegion
+ * @see org.eclipse.jface.text.reconciler.DirtyRegion
  */
 public class Reconciler extends AbstractReconciler implements IReconcilerExtension {
 	
-	/** The map of reconciling strategies */
+	/** The map of reconciling strategies. */
 	private Map fStrategies;
 	
 	/**
@@ -53,7 +54,7 @@ public class Reconciler extends AbstractReconciler implements IReconcilerExtensi
 	 * Creates a new reconciler with the following configuration: it is
 	 * an incremental reconciler with a standard delay of 500 milli-seconds. There
 	 * are no predefined reconciling strategies. The partitioning it uses
-	 * is the default partitioning <code>IDocumentExtension3.DEFAULT_PARTITIONING</code>.
+	 * is the default partitioning {@link IDocumentExtension3#DEFAULT_PARTITIONING}.
 	 */ 
 	public Reconciler() {
 		super();