Javadoc updates

6 files changed, 58 insertions, 6 deletions

diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/IReconcilableModel.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/IReconcilableModel.java
index 288099feefd..f5c71ebf7bb 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/IReconcilableModel.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/IReconcilableModel.java
@@ -12,8 +12,19 @@ package org.eclipse.jface.text.reconciler;
 
 
 /**
- * Tagging interface for a model that can be reconciled.
+ * Tagging interface for a model that can get reconciled during a
+ * {@linkplain org.eclipse.jface.text.reconciler.IReconcileStep reconcile step}.
+ * <p>
+ * This model is not directly used by a {@linkplain org.eclipse.jface.text.reconciler.IReconciler reconciler}
+ * or a {@linkplain org.eclipse.jface.text.reconciler.IReconcilingStrategy reconciling strategy}.
+ * </p>
  * 
+ * <p>
+ * This interface must be implemented by clients that want to use one of
+ * their models as a reconcile step's input model.
+ * </p>
+ * 
+ * @see org.eclipse.jface.text.reconciler.IReconcileStep#setInputModel(IReconcilableModel)
  * @since 3.0
  */
 public interface IReconcilableModel {
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/IReconcileResult.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/IReconcileResult.java
index 7a9ee574c10..58a1cc7fc15 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/IReconcileResult.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/reconciler/IReconcileResult.java
@@ -12,7 +12,12 @@ package org.eclipse.jface.text.reconciler;
 
 
 /**
- * Tagging interface for the result reported by a reconcile step
+ * Tagging interface for the {@linkplain org.eclipse.jface.text.reconciler.IReconcileStep reconcile step}
+ * result's array element type.
+ * <p>
+ * This interface must be implemented by clients that want to
+ * let one of their model elements be part of a reconcile step result.
+ * </p>
  * 
  * @see org.eclipse.jface.text.reconciler.IReconcileStep
  * @since 3.0
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 31d551cd3c3..f51609db9e3 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
@@ -19,8 +19,38 @@ import org.eclipse.jface.text.reconciler.DirtyRegion;
 /**
  * A reconcile step is one of several steps of a
  * {@linkplain org.eclipse.jface.text.reconciler.IReconcilingStrategy reconcile strategy}
- * that consists of several steps.
- * 
+ * that consists of several steps. This relationship is not coded into an interface but
+ * should be used by clients who's reconcile strategy consists of several steps.
+ * <p>
+ * If a reconcile step has an {@linkplain org.eclipse.jface.text.reconciler.IReconcilableModel input model}
+ * it will compute the correct model for the next step in the chain and set the next steps
+ * input model before <code>reconcile</code> gets called on that next step. After the last
+ * step has reconciled the {@linkplain org.eclipse.jface.text.reconciler.IReconcileResult reconcile result}
+ * array gets returned to the previous step. Each step in the chain adapts the result to its
+ * input model and returns it to its previous step.
+ * </p> 
+ * <p>
+ * Example: Assume a strategy consists of steps A, B and C. And the main model is M.
+ * The strategy will set M to be A's input model. What will happen is:
+ * <ol>
+ *	<li>A.setInputModel(M)</li>
+ * 	<li>A.reconcile: A reconciles M</li>
+ *	<li>A computes the model for B =&gt; MB</li>
+ *	<li>B.setInputModel(MB)</li>
+ * 	<li>B.reconcile: B reconciles MB</li>
+ *	<li>B computes the model for C =&gt; MC</li>
+ *	<li>C.setInputModel(MC)</li>
+ * 	<li>C.reconcile: C reconciles MC</li>
+ * 	<li>C returns result RC to step B</li>
+ *	<li>B adapts the RC to MB and merges with its own results</li>
+ * 	<li>B returns result RB to step A</li>
+ *	<li>A adapts the result to M and merges with its own results</li>
+ * 	<li>A returns the result to the reconcile strategy</li>
+ * </ol>
+ * </p>
+ * <p>
+ * This interface must be implemented by clients. 
+ * </p>
  * @since 3.0
  */
 public interface IReconcileStep {
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 8f1de7fae84..71ca386878e 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
@@ -19,6 +19,11 @@ import org.eclipse.jface.text.IRegion;
  * based on text of a particular content type. It provides methods for 
  * incremental as well as non-incremental reconciling.
  * <p>
+ * If a reconcile strategy consists of several steps between which
+ * model transformation is desired the each step should implement
+ * {@link org.eclipse.jface.text.reconciler.IReconcileStep}.
+ * </p>
+ * <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>
diff --git a/org.eclipse.ui.editors/src/org/eclipse/ui/editors/text/FileDocumentProvider.java b/org.eclipse.ui.editors/src/org/eclipse/ui/editors/text/FileDocumentProvider.java
index d3a27c96e34..9ae0fb7d809 100644
--- a/org.eclipse.ui.editors/src/org/eclipse/ui/editors/text/FileDocumentProvider.java
+++ b/org.eclipse.ui.editors/src/org/eclipse/ui/editors/text/FileDocumentProvider.java
@@ -168,7 +168,7 @@ public class FileDocumentProvider extends StorageDocumentProvider {
 		 * Creates a new file synchronizer which is not yet installed on a resource.
 		 * 
 		 * @param fileEditorInput the editor input to be synchronized
-		 * @deprecated use {@link FileDocumentProvider.FileSynchronizer#FileSynchronizer(IFileEditorInput)}
+		 * @deprecated use <code>FileSynchronizer(IFileEditorInput)</code>
 		 */
 		public FileSynchronizer(FileEditorInput fileEditorInput) {
 			fFileEditorInput= fileEditorInput;
diff --git a/org.eclipse.ui.workbench.texteditor/src/org/eclipse/ui/texteditor/templates/TemplatePreferencePage.java b/org.eclipse.ui.workbench.texteditor/src/org/eclipse/ui/texteditor/templates/TemplatePreferencePage.java
index 73e00ba658e..67309ebaeea 100644
--- a/org.eclipse.ui.workbench.texteditor/src/org/eclipse/ui/texteditor/templates/TemplatePreferencePage.java
+++ b/org.eclipse.ui.workbench.texteditor/src/org/eclipse/ui/texteditor/templates/TemplatePreferencePage.java
@@ -779,7 +779,8 @@ public abstract class TemplatePreferencePage extends PreferencePage implements I
 	
 	/**
 	 * Returns the key to use for the formatter preference.
-	 * @return
+	 * 
+	 * @return the formatter preference key
 	 */
 	protected String getFormatterPreferenceKey() {
 		return DEFAULT_FORMATTER_PREFERENCE_KEY;