Javadocv20030320a

22 files changed, 490 insertions, 290 deletions

diff --git a/org.eclipse.text/projection/org/eclipse/jface/text/CoordinatesTranslator.java b/org.eclipse.text/projection/org/eclipse/jface/text/CoordinatesTranslator.java
index bb18e304278..d8ae620c5c8 100644
--- a/org.eclipse.text/projection/org/eclipse/jface/text/CoordinatesTranslator.java
+++ b/org.eclipse.text/projection/org/eclipse/jface/text/CoordinatesTranslator.java
@@ -15,15 +15,31 @@ import java.util.Arrays;
 import java.util.Comparator;
 
 /**
- * 
+ * Implementation of <code>IDocumentInformationMapping</code> matching <code>ProjectionDocument</code> and
+ * <code>ProjectionDocumentManager</code>. The parent document is considered the original document, the projection
+ * document is considered the image document.<p>
+ * This class is for internal use only. 
+ * @since 2.1
  */
 public class CoordinatesTranslator implements IDocumentInformationMapping {
 	
+	/** The parent document */
 	private IDocument fParentDocument;
+	/** The position category used to manage the projected regions of the parent document */
 	private String fParentCategory;
+	/** The projection document */
 	private ProjectionDocument fProjectionDocument;
+	/** The position category to manage the fragments of the projection document. */
 	private String fProjectionCategory;
 	
+	/**
+	 * Creates a new mapping between the given parent document and the given projection document.
+	 * 
+	 * @param parent the parent document
+	 * @param parentCategory the position category of the parent document used to manage the projected regions
+	 * @param projection the projection document
+	 * @param projectionCategory the position category of the projection document used to manage the fragments
+	 */
 	public CoordinatesTranslator(IDocument parent, String parentCategory, ProjectionDocument projection, String projectionCategory) {
 		fParentDocument= parent;
 		fParentCategory= parentCategory;
@@ -31,7 +47,7 @@ public class CoordinatesTranslator implements IDocumentInformationMapping {
 		fProjectionCategory= projectionCategory;
 	}
 	
-	/* (non-Javadoc)
+	/*
 	 * @see org.eclipse.jface.text.IDocumentInformationMapping#toOriginOffset(int)
 	 */
 	public int toOriginOffset(int imageOffset) throws BadLocationException {
@@ -46,7 +62,7 @@ public class CoordinatesTranslator implements IDocumentInformationMapping {
 		return fragment.getOrigin().offset + relative;
 	}
 	
-	/* (non-Javadoc)
+	/*
 	 * @see org.eclipse.jface.text.IDocumentInformationMapping#toOriginRegion(org.eclipse.jface.text.IRegion)
 	 */
 	public IRegion toOriginRegion(IRegion imageRegion) throws BadLocationException {
@@ -65,7 +81,7 @@ public class CoordinatesTranslator implements IDocumentInformationMapping {
 		return new Region(o1, o2 - o1 + 1);
 	}
 	
-	/* (non-Javadoc)
+	/*
 	 * @see org.eclipse.jface.text.IDocumentInformationMapping#toOriginLines(int)
 	 */
 	public IRegion toOriginLines(int imageLine) throws BadLocationException {
@@ -81,7 +97,7 @@ public class CoordinatesTranslator implements IDocumentInformationMapping {
 		return new Region(startLine, endLine - startLine);
 	}
 	
-	/* (non-Javadoc)
+	/*
 	 * @see org.eclipse.jface.text.IDocumentInformationMapping#toOriginLine(int)
 	 */
 	public int toOriginLine(int imageLine) throws BadLocationException {
@@ -91,6 +107,9 @@ public class CoordinatesTranslator implements IDocumentInformationMapping {
 		return lines.getOffset();
 	}
 	
+	/*
+	 * @see org.eclipse.jface.text.IDocumentInformationMapping#toImageOffset(int)
+	 */
 	public int toImageOffset(int originOffset) throws BadLocationException {
 		ProjectionPosition projection= (ProjectionPosition) getPositionOfOffset(fParentDocument, ProjectionDocumentManager.PROJECTION_DOCUMENTS, originOffset);
 		if (projection != null)
@@ -99,6 +118,9 @@ public class CoordinatesTranslator implements IDocumentInformationMapping {
 		return -1;
 	}
 	
+	/*
+	 * @see org.eclipse.jface.text.IDocumentInformationMapping#toImageRegion(org.eclipse.jface.text.IRegion)
+	 */
 	public IRegion toImageRegion(IRegion originRegion) throws BadLocationException {
 		
 		if (originRegion.getLength() == 0) {
@@ -138,7 +160,7 @@ public class CoordinatesTranslator implements IDocumentInformationMapping {
 		return null;
 	}
 	
-	/* (non-Javadoc)
+	/*
 	 * @see org.eclipse.jface.text.IDocumentInformationMapping#toImageLine(int)
 	 */
 	public int toImageLine(int originLine) throws BadLocationException {
@@ -162,12 +184,30 @@ public class CoordinatesTranslator implements IDocumentInformationMapping {
 	
 	//-----------------------------------------------------------------------------------------------------------------------------------
 	
-	
+	/**
+	 * Translates the given offset relative to the given origin position into an
+	 * offset relative to the given target position.
+	 * 
+	 * @param origin the origin position
+	 * @param originOffset the offset relative to <code>originOffset</code>
+	 * @param target the target position
+	 * @return <code>originOffset</code> translated to the given target position
+	 */
 	private int translateOffset(Position origin, int originOffset, Position target) {
 		int relative= originOffset - origin.offset;
 		return target.offset + relative;
 	}
 	
+	/**
+	 * Returns the position of the given category of the given document that includes the given offset
+	 * or <code>null</code> if there is no such position.
+	 * 
+	 * @param document the document
+	 * @param category the position category of <code>document</code>
+	 * @param offset the offset into <code>document</code>
+	 * @return the position including the given offset or <code>null</code>
+	 * @throws BadLocationException if <code>offset</code> is not valid in the given document
+	 */
 	private Position getPositionOfOffset(IDocument document, String category, int offset) throws BadLocationException {
 		try {
 			int index= getPositionIndexOfOffset(document, category, offset, 0);
@@ -180,6 +220,15 @@ public class CoordinatesTranslator implements IDocumentInformationMapping {
 		return null;
 	}
 	
+	/**
+	 * Returns an array of positions of the given category that cover the given range of the document.
+	 * 
+	 * @param document the document
+	 * @param category the position category of <code>document</code>
+	 * @param range the range of <code>document</code>
+	 * @param comparator the comparator to sort the array to be returned
+	 * @return an array of positions that cover the given range in the given document
+	 */
 	private Position[] getPositionsOfRange(IDocument document, String category, IRegion range, Comparator comparator) {
 		
 		int offset= range.getOffset();
@@ -214,6 +263,18 @@ public class CoordinatesTranslator implements IDocumentInformationMapping {
 		return new Position[0];
 	}
 	
+	/**
+	 * Returns the index of the position of the given category of the given document that includes the
+	 * given offset. <code>direction</code> indicates the direction into which the algorithm should search.
+	 * 
+	 * @param document the document
+	 * @param category the position category of <code>document</code>
+	 * @param offset the offset into <code>document</code>
+	 * @param direction the search direction
+	 * @return the index of the position
+	 * @throws BadPositionCategoryException if <code>category</code> is not valid in <code>document</code>
+	 * @throws BadLocationException if <code>offset</code> is not valid in <code>document</code>
+	 */
 	private int getPositionIndexOfOffset(IDocument document, String category, int offset, int direction ) throws BadPositionCategoryException, BadLocationException{
 		
 		Position[] positions= document.getPositions(category);
@@ -241,7 +302,7 @@ public class CoordinatesTranslator implements IDocumentInformationMapping {
 		return -1;
 	}
 	
-	/* (non-Javadoc)
+	/*
 	 * @see org.eclipse.jface.text.IDocumentInformationMapping#getCoverage()
 	 */
 	public IRegion getCoverage() {
@@ -249,7 +310,7 @@ public class CoordinatesTranslator implements IDocumentInformationMapping {
 		return new Region(coverage.getOffset(), coverage.getLength());
 	}
 
-	/* (non-Javadoc)
+	/*
 	 * @see org.eclipse.jface.text.IDocumentInformationMapping#toClosestImageLine(int)
 	 */
 	public int toClosestImageLine(int originLine) throws BadLocationException {
diff --git a/org.eclipse.text/projection/org/eclipse/jface/text/Fragment.java b/org.eclipse.text/projection/org/eclipse/jface/text/Fragment.java
index 66ca92e5115..de6c5fba945 100644
--- a/org.eclipse.text/projection/org/eclipse/jface/text/Fragment.java
+++ b/org.eclipse.text/projection/org/eclipse/jface/text/Fragment.java
@@ -8,13 +8,14 @@
  * Contributors:
  *     IBM Corporation - initial API and implementation
  *******************************************************************************/
-
 package org.eclipse.jface.text;
 
 import org.eclipse.jface.text.Position;
 
 /**
- * Fragment.java
+ * 
+ * This class is for internal use only.
+ * @since 2.1
  */
 public class Fragment extends Position {
 		
@@ -25,10 +26,6 @@ public class Fragment extends Position {
 		fOrigin= origin;
 	}
 	
-//	public Fragment(int offset, int length) {
-//		super(offset, length);
-//	}
-	
 	/**
 	 * Returns the fOrigin.
 	 * @return Position
diff --git a/org.eclipse.text/src/org/eclipse/jface/text/AbstractDocument.java b/org.eclipse.text/src/org/eclipse/jface/text/AbstractDocument.java
index 9f1dd6a920d..4b905f08cc8 100644
--- a/org.eclipse.text/src/org/eclipse/jface/text/AbstractDocument.java
+++ b/org.eclipse.text/src/org/eclipse/jface/text/AbstractDocument.java
@@ -21,12 +21,17 @@ import java.util.Map;
 
 /**
  * Abstract implementation of <code>IDocument</code>. 
- * Implements the complete contract of <code>IDocument</code> and <code>IDocumentExtension</code>.
+ * Implements the complete contract of <code>IDocument</code>, <code>IDocumentExtension</code>,
+ * and <code>IDocumentExtension2</code>.<p>
+ * 
  * An <code>AbstractDocument</code> supports the following implementation plug-ins:
  * <ul>
- * <li> a text store for storing and managing the document's content
+ * <li> a text store for storing and managing the document's content,
  * <li> a line tracker to map character positions to line numbers and vice versa
  * </ul>
+ * The document can dynamically change the text store when switching between 
+ * sequential rewrite mode and normal mode.<p>
+ * 
  * This class must be subclassed. Subclasses must configure which implementation 
  * plug-ins the document should use. Subclasses are not intended to overwrite existing methods.
  *
@@ -86,14 +91,17 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	private int fStoppedListenerNotification= 0;
 	/**
 	 * The document event to be sent after listener notification has been resumed.
+	 * @since 2.1
 	 */
 	private DocumentEvent fDeferredDocumentEvent;
 	/**
 	 * Indicates whether listeners must be notified when listener notification will be resumed.
+	 * @since 2.1
 	 */
 	private boolean fPartitionHasChanged;
 	/**
 	 * The region of changed parititions to be sent when listener notification will be resumed.
+	 * @since 2.1
 	 */
 	private IRegion fChangedPartition;
 	
@@ -172,7 +180,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 		
 	/**
 	 * Sets the document's text store.
-	 * Must be called first inside the constructor.
+	 * Must be called at the beginning of the constructor.
 	 *
 	 * @param store the document's text store
 	 */
@@ -182,7 +190,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	
 	/**
 	 * Sets the document's line tracker. 
-	 * Must be called first inside the constructor.
+	 * Must be called at the beginnng of the constructor.
 	 *
 	 * @param tracker the document's line tracker
 	 */
@@ -191,7 +199,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	}
 		
 	/*
-	 * @see IDocument#setDocumentPartitioner
+	 * @see org.eclipse.jface.text.IDocument#setDocumentPartitioner(org.eclipse.jface.text.IDocumentPartitioner)
 	 */
 	public void setDocumentPartitioner(IDocumentPartitioner partitioner) {
 		fDocumentPartitioner= partitioner;
@@ -222,7 +230,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	//-------------------------------------------------------
 	
 	/*
-	 * @see IDocument#addDocumentListener
+	 * @see org.eclipse.jface.text.IDocument#addDocumentListener(org.eclipse.jface.text.IDocumentListener)
 	 */
 	public void addDocumentListener(IDocumentListener listener) {
 		Assert.isNotNull(listener);
@@ -231,7 +239,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	}
 	
 	/*
-	 * @see IDocument#removeDocumentListener
+	 * @see org.eclipse.jface.text.IDocument#removeDocumentListener(org.eclipse.jface.text.IDocumentListener)
 	 */
 	public void removeDocumentListener(IDocumentListener listener) {
 		Assert.isNotNull(listener);
@@ -256,7 +264,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	}
 	
 	/*
-	 * @see IDocument#addDocumentPartitioningListener
+	 * @see org.eclipse.jface.text.IDocument#addDocumentPartitioningListener(org.eclipse.jface.text.IDocumentPartitioningListener)
 	 */
 	public void addDocumentPartitioningListener(IDocumentPartitioningListener listener) {
 		Assert.isNotNull(listener);
@@ -265,7 +273,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	}
 	
 	/*
-	 * @see IDocument#removeDocumentPartitioningListener
+	 * @see org.eclipse.jface.text.IDocument#removeDocumentPartitioningListener(org.eclipse.jface.text.IDocumentPartitioningListener)
 	 */
 	public void removeDocumentPartitioningListener(IDocumentPartitioningListener listener) {
 		Assert.isNotNull(listener);
@@ -273,7 +281,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	}
 	
 	/*
-	 * @see IDocument#addPosition
+	 * @see org.eclipse.jface.text.IDocument#addPosition(java.lang.String, org.eclipse.jface.text.Position)
 	 */
 	public void addPosition(String category, Position position) throws BadLocationException, BadPositionCategoryException  {
 		
@@ -291,7 +299,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	}
 	
 	/*
-	 * @see IDocument#addPosition
+	 * @see org.eclipse.jface.text.IDocument#addPosition(org.eclipse.jface.text.Position)
 	 */
 	public void addPosition(Position position) throws BadLocationException {
 		try {
@@ -301,7 +309,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	}
 	
 	/*
-	 * @see IDocument#addPositionCategory
+	 * @see org.eclipse.jface.text.IDocument#addPositionCategory(java.lang.String)
 	 */
 	public void addPositionCategory(String category) {
 		
@@ -313,14 +321,14 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	}
 	
 	/*
-	 * @see IDocument#addPositionUpdater
+	 * @see org.eclipse.jface.text.IDocument#addPositionUpdater(org.eclipse.jface.text.IPositionUpdater)
 	 */
 	public void addPositionUpdater(IPositionUpdater updater) {
 		insertPositionUpdater(updater, fPositionUpdaters.size());
 	}
 	
 	/*
-	 * @see IDocument#containsPosition
+	 * @see org.eclipse.jface.text.IDocument#containsPosition(java.lang.String, int, int)
 	 */
 	public boolean containsPosition(String category, int offset, int length) {
 		
@@ -350,7 +358,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	}
 	
 	/*
-	 * @see IDocument#containsPositionCategory
+	 * @see org.eclipse.jface.text.IDocument#containsPositionCategory(java.lang.String)
 	 */
 	public boolean containsPositionCategory(String category) {
 		if (category != null)
@@ -422,9 +430,8 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 		return pos;
 	}
 
-		
 	/*
-	 * @see IDocument#computeIndexInCategory
+	 * @see org.eclipse.jface.text.IDocument#computeIndexInCategory(java.lang.String, int)
 	 */
 	public int computeIndexInCategory(String category, int offset) throws BadLocationException, BadPositionCategoryException {
 		
@@ -441,6 +448,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	/**
 	 * Fires the document partitioning changed notification to all registered 
 	 * document partitioning listeners. Uses a robust iterator.
+	 * 
 	 * @deprecated use <code>fireDocumentPartitioningChanged(IRegion)</code> instead
 	 */
 	protected void fireDocumentPartitioningChanged() {
@@ -461,6 +469,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	 * document partitioning listeners. Uses a robust iterator.
 	 * 
 	 * @param region the region in which partitioning has changed
+	 * 
 	 * @see IDocumentPartitioningListenerExtension
 	 * @since 2.0
 	 */
@@ -563,6 +572,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	 * @param firePartitionChange <code>true</code> if a partition change notification should be sent
 	 * @param partitionChange the region whose partitioning changed
 	 * @see IDocumentExtension
+	 * @since 2.0
 	 */
 	protected void doFireDocumentChanged(DocumentEvent event, boolean firePartitionChange, IRegion partitionChange) {
 		
@@ -616,7 +626,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	}
 	
 	/*
-	 * @see IDocument#getChar
+	 * @see org.eclipse.jface.text.IDocument#getChar(int)
 	 */
 	public char getChar(int pos) throws BadLocationException {
 		if ((0 > pos) || (pos >= getLength()))
@@ -625,7 +635,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	}
 	
 	/*
-	 * @see IDocument#getContentType
+	 * @see org.eclipse.jface.text.IDocument#getContentType(int)
 	 */
 	public String getContentType(int offset) throws BadLocationException {
 		if ((0 > offset) || (offset > getLength()))
@@ -638,7 +648,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	}
 	
 	/*
-	 * @see IDocument#getLegalContentTypes
+	 * @see IDocument#getLegalContentTypes()
 	 */
 	public String[] getLegalContentTypes() {
 		if (fDocumentPartitioner == null)
@@ -647,63 +657,63 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	}
 		
 	/*
-	 * @see IDocument#getLength
+	 * @see IDocument#getLength()
 	 */
 	public int getLength() {
 		return getStore().getLength();
 	}
 	
 	/*
-	 * @see IDocument#getLineDelimiter
+	 * @see org.eclipse.jface.text.IDocument#getLineDelimiter(int)
 	 */
 	public String getLineDelimiter(int line) throws BadLocationException {
 		return getTracker().getLineDelimiter(line);
 	}
 	
 	/*
-	 * @see IDocument#getLegalLineDelimiters
+	 * @see IDocument#getLegalLineDelimiters()
 	 */
 	public String[] getLegalLineDelimiters() {
 		return getTracker().getLegalLineDelimiters();
 	}
 	
 	/*
-	 * @see IDocument#getLineLength
+	 * @see IDocument#getLineLength(int)
 	 */
 	public int getLineLength(int line) throws BadLocationException {
 		return getTracker().getLineLength(line);
 	}
 	
 	/*
-	 * @see IDocument#getLineOfOffset
+	 * @see IDocument#getLineOfOffset(int)
 	 */
 	public int getLineOfOffset(int pos) throws BadLocationException {
 		return getTracker().getLineNumberOfOffset(pos);
 	}
 	
 	/*
-	 * @see IDocument#getLineOffset
+	 * @see IDocument#getLineOffset(int)
 	 */
 	public int getLineOffset(int line) throws BadLocationException {
 		return getTracker().getLineOffset(line);
 	}
 	
 	/*
-	 * @see IDocument#getLineInformation
+	 * @see IDocument#getLineInformation(int)
 	 */
 	public IRegion getLineInformation(int line) throws BadLocationException {
 		return getTracker().getLineInformation(line);
 	}
 	
 	/*
-	 * @see IDocument#getLineInformationOfOffset
+	 * @see IDocument#getLineInformationOfOffset(int)
 	 */
 	public IRegion getLineInformationOfOffset(int offset) throws BadLocationException {
 		return getTracker().getLineInformationOfOffset(offset);
 	}
 	
 	/*
-	 * @see IDocument#getNumberOfLines
+	 * @see IDocument#getNumberOfLines()
 	 */
 	public int getNumberOfLines() {
 		return getTracker().getNumberOfLines();
@@ -724,7 +734,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	}
 	
 	/*
-	 * @see IDocument#getPartition
+	 * @see IDocument#getPartition(int)
 	 */
 	public ITypedRegion getPartition(int offset) throws BadLocationException {
 		if ((0 > offset) || (offset > getLength()))
@@ -737,7 +747,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	}
 	
 	/*
-	 * @see IDocument#computePartitioning
+	 * @see IDocument#computePartitioning(int, int)
 	 */
 	public ITypedRegion[] computePartitioning(int offset, int length) throws BadLocationException {
 		if ((0 > offset) || (0 > length) || (offset + length > getLength()))
@@ -750,7 +760,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	}
 	
 	/*
-	 * @see IDocument#getPositions
+	 * @see IDocument#getPositions(String)
 	 */
 	public Position[] getPositions(String category) throws BadPositionCategoryException {
 		
@@ -767,7 +777,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	}
 	
 	/*
-	 * @see IDocument#getPositionCategories
+	 * @see IDocument#getPositionCategories()
 	 */
 	public String[] getPositionCategories() {
 		String[] categories= new String[fPositions.size()];
@@ -778,7 +788,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	}
 	
 	/*
-	 * @see IDocument#getPositionUpdaters
+	 * @see IDocument#getPositionUpdaters()
 	 */
 	public IPositionUpdater[] getPositionUpdaters() {
 		IPositionUpdater[] updaters= new IPositionUpdater[fPositionUpdaters.size()];
@@ -787,14 +797,14 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	}
 		
 	/*
-	 * @see IDocument#get
+	 * @see IDocument#get()
 	 */
 	public String get() {
 		return getStore().get(0, getLength());
 	}
 	
 	/*
-	 * @see IDocument#get
+	 * @see IDocument#get(int, int)
 	 */
 	public String get(int pos, int length) throws BadLocationException {
 		int myLength= getLength();
@@ -804,7 +814,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	}
 		
 	/*
-	 * @see IDocument#insertPositionUpdater
+	 * @see IDocument#insertPositionUpdater(IPositionUpdater, int)
 	 */
 	public void insertPositionUpdater(IPositionUpdater updater, int index) {
 
@@ -820,7 +830,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	}
  		
 	/*
-	 * @see IDocument#removePosition
+	 * @see org.eclipse.jface.text.IDocument#removePosition(java.lang.String, org.eclipse.jface.text.Position)
 	 */
 	public void removePosition(String category, Position position) throws BadPositionCategoryException {
 		
@@ -845,7 +855,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	}
 	
 	/*
-	 * @see IDocument#removePosition
+	 * @see IDocument#removePosition(Position)
 	 */
 	public void removePosition(Position position) {
 		try {
@@ -855,7 +865,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	}
 		
 	/*
-	 * @see IDocument#removePositionCategory
+	 * @see IDocument#removePositionCategory(String)
 	 */
 	public void removePositionCategory(String category) throws BadPositionCategoryException {
 
@@ -869,7 +879,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	}
 		
 	/*
-	 * @see IDocument#removePositionUpdater
+	 * @see IDocument#removePositionUpdater(IPositionUpdater)
 	 */
 	public void removePositionUpdater(IPositionUpdater updater) {
 		for (int i= fPositionUpdaters.size() - 1; i >= 0; i--) {
@@ -881,7 +891,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	}
 	
 	/*
-	 * @see IDocument#replace
+	 * @see IDocument#replace(int, int, String)
 	 */
 	public void replace(int pos, int length, String text) throws BadLocationException {
 		if ((0 > pos) || (0 > length) || (pos + length > getLength()))
@@ -897,7 +907,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	}
 		
 	/*
-	 * @see IDocument#set
+	 * @see IDocument#set(String)
 	 */
 	public void set(String text) {
 		int length= getStore().getLength();
@@ -928,7 +938,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	}
 	
 	/*
-	 * @see IDocument#search
+	 * @see org.eclipse.jface.text.IDocument#search(int, java.lang.String, boolean, boolean, boolean)
 	 */
 	public int search(int startPosition, String findString, boolean forwardSearch, boolean caseSensitive, boolean wholeWord) throws BadLocationException {
 		
@@ -1150,6 +1160,8 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 		
 		/**
 		 * Creates a new bundle object.
+		 * @param owner the document listener owning the replace operation
+		 * @param replace the replace operation
 		 */
 		RegisteredReplace(IDocumentListener owner, IDocumentExtension.IReplace replace) {
 			fOwner= owner;
@@ -1252,6 +1264,7 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 	
 	/*
 	 * @see org.eclipse.jface.text.IDocumentExtension2#resumeListenerNotification()
+	 * @since 2.1
 	 */
 	public void resumeListenerNotification() {
 		-- fStoppedListenerNotification;
@@ -1262,11 +1275,18 @@ public abstract class AbstractDocument implements IDocument, IDocumentExtension,
 
 	/*
 	 * @see org.eclipse.jface.text.IDocumentExtension2#stopListenerNotification()
+	 * @since 2.1
 	 */
 	public void stopListenerNotification() {
 		++ fStoppedListenerNotification;
 	}
 	
+	/**
+	 * Resumes the document listern notification by sending out the remembered
+	 * partition changed and document event.
+	 * 
+	 * @since 2.1
+	 */
 	private void resumeDocumentListenerNotification() {
 		if (fDeferredDocumentEvent != null) {
 			DocumentEvent event= fDeferredDocumentEvent;
diff --git a/org.eclipse.text/src/org/eclipse/jface/text/AbstractLineTracker.java b/org.eclipse.text/src/org/eclipse/jface/text/AbstractLineTracker.java
index 4ebc59a18aa..aae13944994 100644
--- a/org.eclipse.text/src/org/eclipse/jface/text/AbstractLineTracker.java
+++ b/org.eclipse.text/src/org/eclipse/jface/text/AbstractLineTracker.java
@@ -132,7 +132,7 @@ public abstract class AbstractLineTracker implements ILineTracker {
 	}
 	
 	/*
-	 * @see ILineTracker#getLineLength
+	 * @see ILineTracker#getLineLength(int)
 	 */
 	public int getLineLength(int line) throws BadLocationException {
 		
@@ -149,7 +149,7 @@ public abstract class AbstractLineTracker implements ILineTracker {
 	}
 		
 	/*
-	 * @see ILineTracker#getLineNumberOfOffset
+	 * @see ILineTracker#getLineNumberOfOffset(int)
 	 */
 	public int getLineNumberOfOffset(int position) throws BadLocationException {
 				
@@ -170,7 +170,7 @@ public abstract class AbstractLineTracker implements ILineTracker {
 	}
 	
 	/*
-	 * @see ILineTracker#getLineInformationOfOffset
+	 * @see ILineTracker#getLineInformationOfOffset(int)
 	 */
 	public IRegion getLineInformationOfOffset(int position) throws BadLocationException {		
 		if (position > fTextLength)
@@ -188,7 +188,7 @@ public abstract class AbstractLineTracker implements ILineTracker {
 	}
 	
 	/*
-	 * @see ILineTracker#getLineInformation
+	 * @see ILineTracker#getLineInformation(int)
 	 */
 	public IRegion getLineInformation(int line) throws BadLocationException {
 		
@@ -210,7 +210,7 @@ public abstract class AbstractLineTracker implements ILineTracker {
 	}
 		
 	/*
-	 * @see ILineTracker#getLineOffset
+	 * @see ILineTracker#getLineOffset(int)
 	 */
 	public int getLineOffset(int line) throws BadLocationException {
 		
@@ -232,7 +232,7 @@ public abstract class AbstractLineTracker implements ILineTracker {
 	}
 		
 	/*
-	 * @see ILineTracker#getNumberOfLines
+	 * @see ILineTracker#getNumberOfLines()
 	 */
 	public int getNumberOfLines() {
 		
@@ -455,7 +455,7 @@ public abstract class AbstractLineTracker implements ILineTracker {
 	}
 	
 	/*
-	 * @see ILineTracker#replace
+	 * @see ILineTracker#replace(int, int, String)
 	 */
 	public void replace(int position, int length, String text) throws BadLocationException {
 		
@@ -525,7 +525,7 @@ public abstract class AbstractLineTracker implements ILineTracker {
 	}
 	
 	/*
-	 * @see ILineTracker#set
+	 * @see ILineTracker#set(String)
 	 */
 	public void set(String text) {
 		fLines.clear();
@@ -536,7 +536,7 @@ public abstract class AbstractLineTracker implements ILineTracker {
 	}
 	
 	/*
-	 * @see ILineTracker#getLineDelimiter
+	 * @see ILineTracker#getLineDelimiter(int)
 	 */
 	public String getLineDelimiter(int line) throws BadLocationException {
 		
diff --git a/org.eclipse.text/src/org/eclipse/jface/text/Assert.java b/org.eclipse.text/src/org/eclipse/jface/text/Assert.java
index 1112c1b4143..40d65aba2a1 100644
--- a/org.eclipse.text/src/org/eclipse/jface/text/Assert.java
+++ b/org.eclipse.text/src/org/eclipse/jface/text/Assert.java
@@ -29,143 +29,150 @@ package org.eclipse.jface.text;
  * </p>
  */
 public final class Assert {
+		
+		/**
+		 * <code>AssertionFailedException</code> is a runtime exception thrown
+		 * by some of the methods in <code>Assert</code>.
+		 * <p>
+		 * This class is not declared public to prevent some misuses; programs that catch 
+		 * or otherwise depend on assertion failures are susceptible to unexpected
+		 * breakage when assertions in the code are added or removed.
+		 * </p>
+		 */
+		private static class AssertionFailedException extends RuntimeException {
+	
+			/**
+			 * Constructs a new exception.
+			 */
+			public AssertionFailedException() {
+			}
+			
+			/**
+			 * Constructs a new exception with the given message.
+			 */
+			public AssertionFailedException(String detail) {
+			    super(detail);
+			}
+		}
+		
+	/* This class is not intended to be instantiated. */
+	private Assert() {
+	}
+	
+	/**
+	 * Asserts that an argument is legal. If the given boolean is
+	 * not <code>true</code>, an <code>IllegalArgumentException</code>
+	 * is thrown.
+	 *
+	 * @param expression the outcome of the check
+	 * @return <code>true</code> if the check passes (does not return
+	 *    if the check fails)
+	 * @exception IllegalArgumentException if the legality test failed
+	 */
+	public static boolean isLegal(boolean expression) {
+		// succeed as quickly as possible
+		if (expression) {
+			return true;
+		}
+		return isLegal(expression, "");//$NON-NLS-1$
+	}
+	
+	/**
+	 * Asserts that an argument is legal. If the given boolean is
+	 * not <code>true</code>, an <code>IllegalArgumentException</code>
+	 * is thrown.
+	 * The given message is included in that exception, to aid debugging.
+	 *
+	 * @param expression the outcome of the check
+	 * @param message the message to include in the exception
+	 * @return <code>true</code> if the check passes (does not return
+	 *    if the check fails)
+	 * @exception IllegalArgumentException if the legality test failed
+	 */
+	public static boolean isLegal(boolean expression, String message) {
+		if (!expression)
+			throw new IllegalArgumentException("assertion failed; " + message); //$NON-NLS-1$
+		return expression;
+	}
 	
 	/**
-	 * <code>AssertionFailedException</code> is a runtime exception thrown
-	 * by some of the methods in <code>Assert</code>.
+	 * Asserts that the given object is not <code>null</code>. If this
+	 * is not the case, some kind of unchecked exception is thrown.
 	 * <p>
-	 * This class is not declared public to prevent some misuses; programs that catch 
-	 * or otherwise depend on assertion failures are susceptible to unexpected
-	 * breakage when assertions in the code are added or removed.
+	 * As a general rule, parameters passed to API methods must not be
+	 * <code>null</code> unless <b>explicitly</b> allowed in the method's
+	 * specification. Similarly, results returned from API methods are never
+	 * <code>null</code> unless <b>explicitly</b> allowed in the method's
+	 * specification. Implementations are encouraged to make regular use of 
+	 * <code>Assert.isNotNull</code> to ensure that <code>null</code> 
+	 * parameters are detected as early as possible.
 	 * </p>
+	 * 
+	 * @param object the value to test
+	 * @exception Throwable an unspecified unchecked exception if the object
+	 *   is <code>null</code>
 	 */
-	private static class AssertionFailedException extends RuntimeException {
-
-		/**
-		 * Constructs a new exception.
-		 */
-		public AssertionFailedException() {
-		}
-		
-		/**
-		 * Constructs a new exception with the given message.
-		 */
-		public AssertionFailedException(String detail) {
-		    super(detail);
+	public static void isNotNull(Object object) {
+		// succeed as quickly as possible
+		if (object != null) {
+			return;
 		}
+		isNotNull(object, "");//$NON-NLS-1$
 	}
-/* This class is not intended to be instantiated. */
-private Assert() {
-}
-/**
- * Asserts that an argument is legal. If the given boolean is
- * not <code>true</code>, an <code>IllegalArgumentException</code>
- * is thrown.
- *
- * @param expression the outcome of the check
- * @return <code>true</code> if the check passes (does not return
- *    if the check fails)
- * @exception IllegalArgumentException if the legality test failed
- */
-public static boolean isLegal(boolean expression) {
-	// succeed as quickly as possible
-	if (expression) {
-		return true;
+	
+	/**
+	 * Asserts that the given object is not <code>null</code>. If this
+	 * is not the case, some kind of unchecked exception is thrown.
+	 * The given message is included in that exception, to aid debugging.
+	 * <p>
+	 * As a general rule, parameters passed to API methods must not be
+	 * <code>null</code> unless <b>explicitly</b> allowed in the method's
+	 * specification. Similarly, results returned from API methods are never
+	 * <code>null</code> unless <b>explicitly</b> allowed in the method's
+	 * specification. Implementations are encouraged to make regular use of 
+	 * <code>Assert.isNotNull</code> to ensure that <code>null</code> 
+	 * parameters are detected as early as possible.
+	 * </p>
+	 * 
+	 * @param object the value to test
+	 * @param message the message to include in the exception
+	 * @exception Throwable an unspecified unchecked exception if the object
+	 *   is <code>null</code>
+	 */
+	public static void isNotNull(Object object, String message) {
+		if (object == null)
+			throw new AssertionFailedException("null argument;" + message);//$NON-NLS-1$
 	}
-	return isLegal(expression, "");//$NON-NLS-1$
-}
-/**
- * Asserts that an argument is legal. If the given boolean is
- * not <code>true</code>, an <code>IllegalArgumentException</code>
- * is thrown.
- * The given message is included in that exception, to aid debugging.
- *
- * @param expression the outcome of the check
- * @param message the message to include in the exception
- * @return <code>true</code> if the check passes (does not return
- *    if the check fails)
- * @exception IllegalArgumentException if the legality test failed
- */
-public static boolean isLegal(boolean expression, String message) {
-	if (!expression)
-		throw new IllegalArgumentException("assertion failed; " + message); //$NON-NLS-1$
-	return expression;
-}
-/**
- * Asserts that the given object is not <code>null</code>. If this
- * is not the case, some kind of unchecked exception is thrown.
- * <p>
- * As a general rule, parameters passed to API methods must not be
- * <code>null</code> unless <b>explicitly</b> allowed in the method's
- * specification. Similarly, results returned from API methods are never
- * <code>null</code> unless <b>explicitly</b> allowed in the method's
- * specification. Implementations are encouraged to make regular use of 
- * <code>Assert.isNotNull</code> to ensure that <code>null</code> 
- * parameters are detected as early as possible.
- * </p>
- * 
- * @param object the value to test
- * @exception Throwable an unspecified unchecked exception if the object
- *   is <code>null</code>
- */
-public static void isNotNull(Object object) {
-	// succeed as quickly as possible
-	if (object != null) {
-		return;
+	
+	/**
+	 * Asserts that the given boolean is <code>true</code>. If this
+	 * is not the case, some kind of unchecked exception is thrown.
+	 *
+	 * @param expression the outcome of the check
+	 * @return <code>true</code> if the check passes (does not return
+	 *    if the check fails)
+	 */
+	public static boolean isTrue(boolean expression) {
+		// succeed as quickly as possible
+		if (expression) {
+			return true;
+		}
+		return isTrue(expression, "");//$NON-NLS-1$
 	}
-	isNotNull(object, "");//$NON-NLS-1$
-}
-/**
- * Asserts that the given object is not <code>null</code>. If this
- * is not the case, some kind of unchecked exception is thrown.
- * The given message is included in that exception, to aid debugging.
- * <p>
- * As a general rule, parameters passed to API methods must not be
- * <code>null</code> unless <b>explicitly</b> allowed in the method's
- * specification. Similarly, results returned from API methods are never
- * <code>null</code> unless <b>explicitly</b> allowed in the method's
- * specification. Implementations are encouraged to make regular use of 
- * <code>Assert.isNotNull</code> to ensure that <code>null</code> 
- * parameters are detected as early as possible.
- * </p>
- * 
- * @param object the value to test
- * @param message the message to include in the exception
- * @exception Throwable an unspecified unchecked exception if the object
- *   is <code>null</code>
- */
-public static void isNotNull(Object object, String message) {
-	if (object == null)
-		throw new AssertionFailedException("null argument;" + message);//$NON-NLS-1$
-}
-/**
- * Asserts that the given boolean is <code>true</code>. If this
- * is not the case, some kind of unchecked exception is thrown.
- *
- * @param expression the outcome of the check
- * @return <code>true</code> if the check passes (does not return
- *    if the check fails)
- */
-public static boolean isTrue(boolean expression) {
-	// succeed as quickly as possible
-	if (expression) {
-		return true;
+	
+	/**
+	 * Asserts that the given boolean is <code>true</code>. If this
+	 * is not the case, some kind of unchecked exception is thrown.
+	 * The given message is included in that exception, to aid debugging.
+	 *
+	 * @param expression the outcome of the check
+	 * @param message the message to include in the exception
+	 * @return <code>true</code> if the check passes (does not return
+	 *    if the check fails)
+	 */
+	public static boolean isTrue(boolean expression, String message) {
+		if (!expression)
+			throw new AssertionFailedException("Assertion failed: "+message);//$NON-NLS-1$
+		return expression;
 	}
-	return isTrue(expression, "");//$NON-NLS-1$
-}
-/**
- * Asserts that the given boolean is <code>true</code>. If this
- * is not the case, some kind of unchecked exception is thrown.
- * The given message is included in that exception, to aid debugging.
- *
- * @param expression the outcome of the check
- * @param message the message to include in the exception
- * @return <code>true</code> if the check passes (does not return
- *    if the check fails)
- */
-public static boolean isTrue(boolean expression, String message) {
-	if (!expression)
-		throw new AssertionFailedException("Assertion failed: "+message);//$NON-NLS-1$
-	return expression;
-}
 }
diff --git a/org.eclipse.text/src/org/eclipse/jface/text/ChildDocument.java b/org.eclipse.text/src/org/eclipse/jface/text/ChildDocument.java
index c46804ef8f9..7eb112f3cc7 100644
--- a/org.eclipse.text/src/org/eclipse/jface/text/ChildDocument.java
+++ b/org.eclipse.text/src/org/eclipse/jface/text/ChildDocument.java
@@ -14,9 +14,14 @@ package org.eclipse.jface.text;
 
 
 /**
- * A child document represent a range of its parent document. 
- * The child document is always in sync with its parent document
- * by utilizing the parent document as its <code>ITextStore</code>.
+ * A child document is one particular example of a slave document. Child documents
+ * are created by the <code>ChildDocumentManager</code>, an implementation of
+ * <code>ISlaveDocumentManager</code>.<p>
+ * 
+ * A child document represents one consequetive range of its master document.
+ * The master document is called parent document. The child document is always in sync 
+ * with its parent document by utilizing the parent document as its <code>ITextStore</code>.<p>
+ * 
  * This class is for internal use only.
  *
  * @see ITextStore
@@ -25,12 +30,12 @@ public final class ChildDocument extends AbstractDocument {
 	
 	
 	/**
-	 * Implements ITextStore based on IDocument.
+	 * Implements <code>ITextStore</code> based on <code>IDocument</code>.
 	 */
 	class TextStore implements ITextStore {
 		
 		/*
-		 * @see ITextStore#set
+		 * @see ITextStore#set(String)
 		 */
 		public void set(String txt) {
 			try {
@@ -41,7 +46,7 @@ public final class ChildDocument extends AbstractDocument {
 		}
 		
 		/*
-		 * @see ITextStore#replace
+		 * @see ITextStore#replace(int, int, String)
 		 */
 		public void replace(int offset, int length, String txt) {
 			try {
@@ -52,14 +57,14 @@ public final class ChildDocument extends AbstractDocument {
 		}
 		
 		/*
-		 * @see ITextStore#getLength
+		 * @see ITextStore#getLength()
 		 */
 		public int getLength() {
 			return fRange.getLength();
 		}
 		
 		/*
-		 * @see ITextStore#get
+		 * @see ITextStore#get(int, int)
 		 */
 		public String get(int offset, int length) {
 			try {
@@ -71,7 +76,7 @@ public final class ChildDocument extends AbstractDocument {
 		}
 		
 		/*
-		 * @see ITextStore#get
+		 * @see ITextStore#get(int)
 		 */
 		public char get(int offset) {
 			try {
@@ -88,16 +93,15 @@ public final class ChildDocument extends AbstractDocument {
 	/** The parent document */
 	private IDocument fParentDocument;
 	/** 
-	 * The parent document as document extension
+	 * The parent document as <code>IDocumentExtension</code>
 	 * @since 2.0
 	 */
 	private IDocumentExtension fExtension;
 	/**
-	 * The parent document as document extension 2
+	 * The parent document as <code>IDocumentExtension2</code>
 	 * @since 2.1
 	 */
 	private IDocumentExtension2 fExtension2;
-	
 	/** The section inside the parent document */
 	private Position fRange;
 	/** The document event issued by the parent document */
@@ -106,13 +110,23 @@ public final class ChildDocument extends AbstractDocument {
 	private DocumentEvent fEvent;
 	/** Indicates whether the child document initiated a parent document update or not */
 	private boolean fIsUpdating= false;
-	/** The expected document content after the parent document changed. */
+	/** 
+	 * The expected document content after the parent document changed.
+	 * @since 2.1
+	 */
 	private String fExpectedContent;
-	/** The length of this child document prior to the change of the parent document */
+	/** 
+	 * The length of this child document prior to the change of the parent document
+	 * @since 2.1
+	 */
 	private int fRememberedLength;
-	/** Indicates whether this document is in autpo expand mode */
+	/** 
+	 * Indicates whether this document is in auto expand mode.
+	 * @since 2.1
+	 */
 	private boolean fIsAutoExpanding= false;
 	
+	
 	/**
 	 * Creates a child document for the given range of the given parent document.
 	 *
@@ -177,7 +191,8 @@ public final class ChildDocument extends AbstractDocument {
 		
 	/**
 	 * <p>Transforms a document event of the parent document into a child document
-	 * based document event. </p>
+	 * based document event. This method considers whether the document is in 
+	 * auto expand mode.</p>
 	 * This method is public for test purposes only.
 	 *
 	 * @param e the parent document event
@@ -255,7 +270,7 @@ public final class ChildDocument extends AbstractDocument {
 	/**
 	 * When called this child document is informed about a forthcoming change
 	 * of its parent document. This child document checks whether the parent
-	 * document changed affects it and if so informs all document listeners.
+	 * document change affects it and if so informs all document listeners.
 	 *
 	 * @param event the parent document event
 	 */
@@ -305,7 +320,7 @@ public final class ChildDocument extends AbstractDocument {
 	}
 	
 	/*
-	 * @see AbstractDocument#fireDocumentAboutToBeChanged
+	 * @see AbstractDocument#fireDocumentAboutToBeChanged(DocumentEvent)
 	 */
 	protected void fireDocumentAboutToBeChanged(DocumentEvent event) {
 		// delay it until there is a notification from the parent document
@@ -417,15 +432,20 @@ public final class ChildDocument extends AbstractDocument {
 	
 	/**
 	 * Sets the auto expand mode of this document.
+	 * 
 	 * @param autoExpand <code>true</code> if auto expanding, <code>false</code> otherwise
+	 * @since 2.1
 	 */
 	public void setAutoExpandMode(boolean autoExpand) {
 		fIsAutoExpanding= autoExpand;
 	}
 	
 	/**
-	 * Returns this document's auto expand mode.
-	 * @return this document's auto expand mode
+	 * Returns whether the given document might cause this document to auto expand.
+	 * This default implementation always answers with its auto expand state.
+	 * 
+	 * @param event the document event
+	 * @return <code>true</code> if the given event might cause this document to auto expand
 	 */	
 	public boolean isAutoExpandEvent(DocumentEvent event) {
 		return fIsAutoExpanding;
diff --git a/org.eclipse.text/src/org/eclipse/jface/text/ChildDocumentManager.java b/org.eclipse.text/src/org/eclipse/jface/text/ChildDocumentManager.java
index d2e5d3c8faa..b7bc5610177 100644
--- a/org.eclipse.text/src/org/eclipse/jface/text/ChildDocumentManager.java
+++ b/org.eclipse.text/src/org/eclipse/jface/text/ChildDocumentManager.java
@@ -13,7 +13,10 @@ package org.eclipse.jface.text;
 
 
 /**
- * Manages a set of child documents for given parent documents. 
+ * <code>ChildDocumentManager</code> is one particular implementation of 
+ * <code>ISlaveDocumentManager</code>. This manager creates so called child
+ * documents as slave documents for given master documents.<p>
+ * 
  * A child document represents a particular range of the parent 
  * document and is accordingly adapted to changes of the parent document. 
  * Vice versa, the parent document is accordingly adapted to changes of
@@ -27,7 +30,7 @@ public final class ChildDocumentManager implements IDocumentListener, ISlaveDocu
 	
 	
 	/** 
-	 * Name of the position categories used to keep track of the child
+	 * Name of the position category used to keep track of the child
 	 * documents offset ranges into the parent document.
 	 */
 	public final static String CHILDDOCUMENTS= "__childdocuments"; //$NON-NLS-1$
@@ -40,9 +43,17 @@ public final class ChildDocumentManager implements IDocumentListener, ISlaveDocu
 	 */
 	static class ChildPosition extends Position {
 		
+		/** The parent document. */
 		public IDocument fParentDocument;
+		/* The child document */
 		public ChildDocument fChildDocument;
 		
+		/**
+		 * Creates a new child position for the given parent document.
+		 * @param parentDocument the parent document
+		 * @param offset the offset into the parent document
+		 * @param length the length in the parent document
+		 */
 		public ChildPosition(IDocument parentDocument, int offset, int length) {
 			super(offset, length);
 			fParentDocument= parentDocument;
@@ -136,7 +147,14 @@ public final class ChildDocumentManager implements IDocumentListener, ISlaveDocu
 				}
 			}
 		}
-	
+		
+		/**
+		 * Returns whether the child documents should automatically expand to include
+		 * any parent document change.
+		 * 
+		 * @return <code>true</code> if auto expanding, <code>false</code> otherwise
+		 * @since 2.1
+		 */
 		private boolean isAutoExpanding() {
 			if (fPosition instanceof ChildPosition) {
 				ChildPosition position= (ChildPosition) fPosition;
@@ -151,9 +169,14 @@ public final class ChildDocumentManager implements IDocumentListener, ISlaveDocu
 	 */
 	static class ChildPartitioner implements IDocumentPartitioner {
 		
+		/** The child document. */
 		protected ChildDocument fChildDocument;
+		/** The parent document */
 		protected IDocument fParentDocument;
 		
+		/** 
+		 * Creates a new child document partitioner.
+		 */
 		protected ChildPartitioner() {
 		}
 		
@@ -253,7 +276,7 @@ public final class ChildDocumentManager implements IDocumentListener, ISlaveDocu
 		return fChildPositionUpdater;
 	}
 	
-	 /* (non-Javadoc)
+	 /*
 	 * @see org.eclipse.jface.text.ISlaveDocumentManager#createSlaveDocument(org.eclipse.jface.text.IDocument)
 	 */
 	public IDocument createSlaveDocument(IDocument master)  {
@@ -283,7 +306,7 @@ public final class ChildDocumentManager implements IDocumentListener, ISlaveDocu
 		return child;
 	}
 	
-	/* (non-Javadoc)
+	/*
 	 * @see org.eclipse.jface.text.ISlaveDocumentManager#freeSlaveDocument(org.eclipse.jface.text.IDocument)
 	 */
 	public void freeSlaveDocument(IDocument slave) {
@@ -311,7 +334,7 @@ public final class ChildDocumentManager implements IDocumentListener, ISlaveDocu
 		}
 	}
 	
-	/* (non-Javadoc)
+	/*
 	 * @see org.eclipse.jface.text.ISlaveDocumentManager#createMasterSlaveMapping(org.eclipse.jface.text.IDocument)
 	 */
 	public IDocumentInformationMapping createMasterSlaveMapping(IDocument slave) {
@@ -320,7 +343,7 @@ public final class ChildDocumentManager implements IDocumentListener, ISlaveDocu
 		return null;
 	}
 	
-	/* (non-Javadoc)
+	/*
 	 * @see org.eclipse.jface.text.ISlaveDocumentManager#getMasterDocument(org.eclipse.jface.text.IDocument)
 	 */
 	public IDocument getMasterDocument(IDocument slave) {
@@ -329,7 +352,7 @@ public final class ChildDocumentManager implements IDocumentListener, ISlaveDocu
 		return null;
 	}
 	
-	/* (non-Javadoc)
+	/*
 	 * @see org.eclipse.jface.text.ISlaveDocumentManager#isSlaveDocument(org.eclipse.jface.text.IDocument)
 	 */
 	public boolean isSlaveDocument(IDocument document) {
diff --git a/org.eclipse.text/src/org/eclipse/jface/text/ConfigurableLineTracker.java b/org.eclipse.text/src/org/eclipse/jface/text/ConfigurableLineTracker.java
index edc806cce08..301b64c41d2 100644
--- a/org.eclipse.text/src/org/eclipse/jface/text/ConfigurableLineTracker.java
+++ b/org.eclipse.text/src/org/eclipse/jface/text/ConfigurableLineTracker.java
@@ -42,7 +42,7 @@ public class ConfigurableLineTracker extends AbstractLineTracker {
 	}
 	
 	/*
-	 * @see ILineDelimiter@getLegalLineDelimiters
+	 * @see ILineDelimiter@getLegalLineDelimiters()
 	 */
 	public String[] getLegalLineDelimiters() {
 		return fDelimiters;
diff --git a/org.eclipse.text/src/org/eclipse/jface/text/DefaultLineTracker.java b/org.eclipse.text/src/org/eclipse/jface/text/DefaultLineTracker.java
index cc3683f3b17..f7d68bba574 100644
--- a/org.eclipse.text/src/org/eclipse/jface/text/DefaultLineTracker.java
+++ b/org.eclipse.text/src/org/eclipse/jface/text/DefaultLineTracker.java
@@ -34,7 +34,7 @@ public class DefaultLineTracker extends AbstractLineTracker {
 	}
 	
 	/*
-	 * @see ILineDelimiter@getLegalLineDelimiters
+	 * @see ILineDelimiter@getLegalLineDelimiters()
 	 */
 	public String[] getLegalLineDelimiters() {
 		return DELIMITERS;
diff --git a/org.eclipse.text/src/org/eclipse/jface/text/DefaultPositionUpdater.java b/org.eclipse.text/src/org/eclipse/jface/text/DefaultPositionUpdater.java
index 4daca7f89ca..96bae42a36f 100644
--- a/org.eclipse.text/src/org/eclipse/jface/text/DefaultPositionUpdater.java
+++ b/org.eclipse.text/src/org/eclipse/jface/text/DefaultPositionUpdater.java
@@ -39,7 +39,10 @@ public class DefaultPositionUpdater implements IPositionUpdater {
 	
 	/** Caches the currently investigated position */
 	protected Position fPosition;
-	/** Remembers the original state of the investigated position */
+	/** 
+	 * Remembers the original state of the investigated position
+	 * @since 2.1
+	 */
 	protected Position fOriginalPosition= new Position(0, 0);
 	/** Caches the offset of the replaced text */
 	protected int fOffset;
diff --git a/org.eclipse.text/src/org/eclipse/jface/text/Document.java b/org.eclipse.text/src/org/eclipse/jface/text/Document.java
index f6eca84720c..b3fa42bc8ba 100644
--- a/org.eclipse.text/src/org/eclipse/jface/text/Document.java
+++ b/org.eclipse.text/src/org/eclipse/jface/text/Document.java
@@ -13,12 +13,14 @@ package org.eclipse.jface.text;
 
 
 /**
- * Default document implementation. Uses a gap text store as text store and
- * installs a line tracker considering the following strings as line delimiters
+ * Default document implementation. Uses a <code>GapTextStore</code> as default
+ * text store and a <code>SequentialRewriteTextStore</code> when in sequential
+ * rewrite mode. The used line tracker considers the following strings as line delimiters
  * "\n", "\r", "\r\n". The document is ready to use. It has a default position
  * category for which a default position updater is installed.
  *
- * @see GapTextStore
+ * @see org.eclipse.jface.text.GapTextStore
+ * @see org.eclipse.jface.text.SequentialRewriteTextStore
  */
 public class Document extends AbstractDocument {
 	
diff --git a/org.eclipse.text/src/org/eclipse/jface/text/GapTextStore.java b/org.eclipse.text/src/org/eclipse/jface/text/GapTextStore.java
index 50b6b338591..e0946cb613f 100644
--- a/org.eclipse.text/src/org/eclipse/jface/text/GapTextStore.java
+++ b/org.eclipse.text/src/org/eclipse/jface/text/GapTextStore.java
@@ -130,7 +130,7 @@ public class GapTextStore implements ITextStore {
 	}
 	
 	/*
-	 * @see ITextStore#get
+	 * @see ITextStore#get(int)
 	 */
 	public char get(int offset) {
 		
@@ -142,7 +142,7 @@ public class GapTextStore implements ITextStore {
 	}
 	
 	/*
-	 * @see ITextStore#get
+	 * @see ITextStore#get(int, int)
 	 */
 	public String get(int offset, int length) {
 
@@ -166,7 +166,7 @@ public class GapTextStore implements ITextStore {
 	}
 	
 	/*
-	 * @see ITextStore#getLength
+	 * @see ITextStore#getLength()
 	 */
 	public int getLength() {
 		int length= fGapEnd - fGapStart;
@@ -175,7 +175,7 @@ public class GapTextStore implements ITextStore {
 	
 	
 	/*
-	 * @see ITextStore#replace
+	 * @see ITextStore#replace(int, int, String)
 	 */
 	public void replace(int offset, int length, String text) {
 		
@@ -214,7 +214,7 @@ public class GapTextStore implements ITextStore {
 	 * Sets the content to <code>text</code> and removes the gap
 	 * since there are no sensible predictions about 
 	 * where the next change will occur.
-	 * @see ITextStore#set
+	 * @see ITextStore#set(String)
 	 */
 	public void set(String text) {
 		
diff --git a/org.eclipse.text/src/org/eclipse/jface/text/IDocumentExtension2.java b/org.eclipse.text/src/org/eclipse/jface/text/IDocumentExtension2.java
index 9cdc5f762ff..c785a6761ff 100644
--- a/org.eclipse.text/src/org/eclipse/jface/text/IDocumentExtension2.java
+++ b/org.eclipse.text/src/org/eclipse/jface/text/IDocumentExtension2.java
@@ -39,7 +39,9 @@ public interface IDocumentExtension2 {
 	 * <code>replace</code> <code>resumeListenerNotification</code> must be
 	 * called. The affect of these calls is that no document listener is notified
 	 * until <code>resumeListenerNotification</code> is called. This allows clients
-	 * to update structure before any listener is informed about the change.
+	 * to update structure before any listener is informed about the change.<p>
+	 * Listener notification can only be stopped for a single document manipulation.
+	 * Otherwise, document change notifications will be lost.
 	 */
 	void stopListenerNotification();
 	
diff --git a/org.eclipse.text/src/org/eclipse/jface/text/IDocumentPartitionerExtension.java b/org.eclipse.text/src/org/eclipse/jface/text/IDocumentPartitionerExtension.java
index f96728b94f8..a7d636c15e8 100644
--- a/org.eclipse.text/src/org/eclipse/jface/text/IDocumentPartitionerExtension.java
+++ b/org.eclipse.text/src/org/eclipse/jface/text/IDocumentPartitionerExtension.java
@@ -15,7 +15,10 @@ package org.eclipse.jface.text;
 /**
  * Extension interface for <code>IDocumentPartitioner</code>. Extends the original
  * concept of a document partitioner by returning the minimal region that includes all
- * partition changes causes by the invocation of the document partitioner.
+ * partition changes caused by the invocation of the document partitioner.
+ * 
+ * The method <code>documentChanged2</code> is considered the replacement of
+ * <code>IDocumentPartitioner.documentChanged</code>.
  * 
  * @since 2.0
 
@@ -24,11 +27,12 @@ public interface IDocumentPartitionerExtension {
 		
 	/**
 	 * The document has been changed. The partitioner updates 
-	 * the document's partitioning and returns in which region the
-	 * partition types have changed. This method always returns
-	 * the surrounding region. Will be called by the connected document
-	 * and is not intended to be used by clients other than the connected
-	 * document.
+	 * the document's partitioning and returns the minimal region that comprises
+	 * all partition changes caused by the given document event. This method returns
+	 * <code>null</code> if the partitioning did not change.<p>
+	 * 
+	 * Will be called by the connected document and is not intended to be used by
+	 * clients other than the connected document.
 	 *
 	 * @param event the event describing the document change
 	 * @return the region of the document in which the partition type changed
diff --git a/org.eclipse.text/src/org/eclipse/jface/text/ILineTracker.java b/org.eclipse.text/src/org/eclipse/jface/text/ILineTracker.java
index 9549fedef4f..837b845c65e 100644
--- a/org.eclipse.text/src/org/eclipse/jface/text/ILineTracker.java
+++ b/org.eclipse.text/src/org/eclipse/jface/text/ILineTracker.java
@@ -14,7 +14,7 @@ package org.eclipse.jface.text;
 
 /**
  * A line tracker maps character positions to line numbers and vice versa.
- * Initially the line tracker is informed about its underlying text which
+ * Initially the line tracker is informed about its underlying text
  * in order to initialize the mapping information. After that, the line 
  * tracker is informed about all changes of the underlying text allowing 
  * for incremental updates of the mapping information. It is the client's
diff --git a/org.eclipse.text/src/org/eclipse/jface/text/ISlaveDocumentManager.java b/org.eclipse.text/src/org/eclipse/jface/text/ISlaveDocumentManager.java
index 4f82b5d3036..98e9d4828ea 100644
--- a/org.eclipse.text/src/org/eclipse/jface/text/ISlaveDocumentManager.java
+++ b/org.eclipse.text/src/org/eclipse/jface/text/ISlaveDocumentManager.java
@@ -12,57 +12,81 @@
 package org.eclipse.jface.text;
 
 /**
- * Slave documents are documents that use a text store which is based on a
- * master document.
+ * Slave documents are documents whose contents is defined in terms of a master
+ * document. Thus, slave documents usually reflect a projection of the master document.
+ * Slave documents are causally connected to the master document. This means, changes
+ * of the master document have immediate effect in the slave document and vice versa.<p>
+ * 
+ * A slave document manager creates slave documents for given master documents. manages the
+ * life cycle of the slave documents and keeps track of the information flow between
+ * master and slave documents. The slave document manager defines the construction rules of the
+ * slave documents in terms of the master document.<p>
+ * 
  * @since 2.1
  */
 public interface ISlaveDocumentManager {
 	
 	/**
-	 * Creates a new slave document for the given master document.
+	 * Creates a new slave document for the given master document. The slave document
+	 * is causally connected to its master document until <code>freeSlaveDocument</code>
+	 * is called. The connection between the newly created slave document and the master
+	 * document is managed by this slave document manager.
 	 * 
-	 * @param master
-	 * @return IDocument
+	 * @param master the master document
+	 * @return the newly created slave document
+	 * @see ISlaveDocumentManager#freeSlaveDocument(IDocument)
 	 */
 	IDocument createSlaveDocument(IDocument master);
 	
 	/**
-	 * Frees the given slave document.
+	 * Frees the given slave document. If the given document is not a slave document known
+	 * to this slave document manager, this call does not have any effect. A slave
+	 * document is known to this slave document manager if it has been created by
+	 * this manager using <code>createSlaveDocument</code>.
 	 * 
-	 * @param slave
+	 * @param slave the slave document to be freed
 	 */
 	void freeSlaveDocument(IDocument slave);
 	
 	/**
-	 * Creates a new mapping between the given slave document and its master.
+	 * Creates a new document information mapping between the given slave document and
+	 * its master document. Returns <code>null</code> if the given document is unknown
+	 * to this slave document manager.
 	 * 
-	 * @param slaveDocument
-	 * @return IDocumentInformationMapping
+	 * @param slave the slave document
+	 * @return a document information mapping between the slave document and its master document or
+	 * 		<code>null</code>
 	 */
 	IDocumentInformationMapping createMasterSlaveMapping(IDocument slave);
 	
 	/**
-	 * Returns the master of the given slave document.
+	 * Returns the master document of the given slave document or <code>null</code> if the
+	 * given document is unknown to this slave document manager.
 	 * 
-	 * @param slave
-	 * @return IDocument
+	 * @param slave the slave document
+	 * @return the master document of the given slave document or <code>null</code>
 	 */
 	IDocument getMasterDocument(IDocument slave);
 	
 	/**
-	 * Method isSlaveDocument.
-	 * @param document
-	 * @return boolean
+	 * Returns whether the given document is a slave document known to this slave document manager. A slave document
+	 * is known to this slave document manager, if the document has been created by this manager.
+	 * 
+	 * @param document the document to be checked whether it is a slave document known to this manager
+	 * @return <code>true</code> if the document is a slave document, <code>false</code> otherwise
 	 */
 	boolean isSlaveDocument(IDocument document);
 	
 	/**
-	 * Sets the given document's auto expand mode. In auto expand mode, a
-	 * slave is expanded to include all of the master document affected by
-	 * document changes.
+	 * Sets the given slave document's auto expand mode. In auto expand mode, a
+	 * slave document is automatically adapted to reflect all changes applied to it's master document.
+	 * Assume a master document contains 30 lines and the slave is defined to contain the lines 11-20.
+	 * In auto expand mode, when the master document is changed at line 8, the slave document is expanded
+	 * to contain the lines 8-20.<p>
+	 * This call is without effect if the given document is unknown to this slave document manager.
 	 * 
 	 * @param slave the slave whose auto expand mode should be set
-	 * @param autoExpand the mode
+	 * @param autoExpand <code>true</code> for auto expand, <code>false</code> otherwise
 	 */
 	void setAutoExpandMode(IDocument slave, boolean autoExpand);
 }
diff --git a/org.eclipse.text/src/org/eclipse/jface/text/ITextStore.java b/org.eclipse.text/src/org/eclipse/jface/text/ITextStore.java
index 289f9fcb0ad..b11b23aeb12 100644
--- a/org.eclipse.text/src/org/eclipse/jface/text/ITextStore.java
+++ b/org.eclipse.text/src/org/eclipse/jface/text/ITextStore.java
@@ -14,7 +14,7 @@ package org.eclipse.jface.text;
 /**
  * Interface for storing and managing text.
  * Provides access to the stored text and allows to manipulate it.
- * Clients may implement this interface.
+ * Clients may implement this interface or use <code>GapTextStore</code>.
  */
 public interface ITextStore {
 	
diff --git a/org.eclipse.text/src/org/eclipse/jface/text/ParentChildMapping.java b/org.eclipse.text/src/org/eclipse/jface/text/ParentChildMapping.java
index 160b1a718a1..4016f59ee97 100644
--- a/org.eclipse.text/src/org/eclipse/jface/text/ParentChildMapping.java
+++ b/org.eclipse.text/src/org/eclipse/jface/text/ParentChildMapping.java
@@ -11,20 +11,30 @@
 package org.eclipse.jface.text;
 
 /**
- * ParentChildMapping.java
+ * Implementation of <code>IDocumentInformationMapping</code> matching <code>ChildDocument</code> and
+ * <code>ChildDocumentManager</code>. The parent document is considered the original document, the child
+ * document is considered the image document.
  */
 public class ParentChildMapping  implements IDocumentInformationMapping {
 	
+	/** The parent document */
 	private IDocument fParentDocument;
+	/** The child document */
 	private ChildDocument fChildDocument;
 	
 	
+	/**
+	 * Creates a new document mapping between the parent document of the given
+	 * child document and the child document.
+	 * 
+	 * @param childDocument
+	 */
 	public ParentChildMapping(ChildDocument childDocument) {
 		fParentDocument= childDocument.getParentDocument();
 		fChildDocument= childDocument;
 	}
 	
-	/* (non-Javadoc)
+	/*
 	 * @see org.eclipse.jface.text.IDocumentInformationMapping#getCoverage()
 	 */
 	public IRegion getCoverage() {
@@ -32,7 +42,7 @@ public class ParentChildMapping  implements IDocumentInformationMapping {
 		return new Region(p.getOffset(), p.getLength());
 	}
 	
-	/* (non-Javadoc)
+	/*
 	 * @see org.eclipse.jface.text.IDocumentInformationMapping#toOriginOffset(int)
 	 */
 	public int toOriginOffset(int imageOffset) throws BadLocationException {
@@ -40,7 +50,7 @@ public class ParentChildMapping  implements IDocumentInformationMapping {
 		return anchorOffset + imageOffset;
 	}
 	
-	/* (non-Javadoc)
+	/*
 	 * @see org.eclipse.jface.text.IDocumentInformationMapping#toOriginRegion(org.eclipse.jface.text.IRegion)
 	 */
 	public IRegion toOriginRegion(IRegion imageRegion) throws BadLocationException {
@@ -48,7 +58,7 @@ public class ParentChildMapping  implements IDocumentInformationMapping {
 		return new Region(anchorOffset + imageRegion.getOffset(), imageRegion.getLength());
 	}
 
-	/* (non-Javadoc)
+	/*
 	 * @see org.eclipse.jface.text.IDocumentInformationMapping#toOriginLines(int)
 	 */
 	public IRegion toOriginLines(int imageLine) throws BadLocationException {
@@ -63,7 +73,7 @@ public class ParentChildMapping  implements IDocumentInformationMapping {
 		return new Region(startLine, endLine - startLine);
 	}
 
-	/* (non-Javadoc)
+	/*
 	 * @see org.eclipse.jface.text.IDocumentInformationMapping#toOriginLine(int)
 	 */
 	public int toOriginLine(int imageLine) throws BadLocationException {
@@ -71,7 +81,7 @@ public class ParentChildMapping  implements IDocumentInformationMapping {
 		return fParentDocument.getLineOfOffset(anchorOffset) + imageLine;
 	}
 	
-	/* (non-Javadoc)
+	/*
 	 * @see org.eclipse.jface.text.IDocumentInformationMapping#toImageOffset(int)
 	 */
 	public int toImageOffset(int originOffset) throws BadLocationException {
@@ -81,7 +91,7 @@ public class ParentChildMapping  implements IDocumentInformationMapping {
 		return -1;
 	}
 	
-	/* (non-Javadoc)
+	/*
 	 * @see org.eclipse.jface.text.IDocumentInformationMapping#toImageRegion(org.eclipse.jface.text.IRegion)
 	 */
 	public IRegion toImageRegion(IRegion originRegion) throws BadLocationException {
@@ -116,7 +126,7 @@ public class ParentChildMapping  implements IDocumentInformationMapping {
 		return null;
 	}
 	
-	/* (non-Javadoc)
+	/*
 	 * @see org.eclipse.jface.text.IDocumentInformationMapping#toImageLine(int)
 	 */
 	public int toImageLine(int originLine) throws BadLocationException {
@@ -129,7 +139,7 @@ public class ParentChildMapping  implements IDocumentInformationMapping {
 		return imageLine;
 	}
 	
-	/* (non-Javadoc)
+	/*
 	 * @see org.eclipse.jface.text.IDocumentInformationMapping#toClosestImageLine(int)
 	 */
 	public int toClosestImageLine(int originLine) throws BadLocationException {
diff --git a/org.eclipse.text/src/org/eclipse/jface/text/Position.java b/org.eclipse.text/src/org/eclipse/jface/text/Position.java
index 85bb12a405a..b11a53e85f0 100644
--- a/org.eclipse.text/src/org/eclipse/jface/text/Position.java
+++ b/org.eclipse.text/src/org/eclipse/jface/text/Position.java
@@ -13,7 +13,7 @@ package org.eclipse.jface.text;
 
  
 /**
- * Positions describe text ranges of a document and are
+ * Positions describe text ranges of a document. Positions are
  * adapted to changes applied to that document. The text range 
  * is specified by an offset and a length. Positions can be marked as
  * deleted. Deleted positions are considered to no longer represent 
@@ -87,7 +87,7 @@ public class Position {
 	}
 	
 	/*
-	 * @see Object#equals
+	 * @see Object#equals(Object)
 	 */
 	public boolean equals(Object other) {
 		if (other instanceof Position) {
diff --git a/org.eclipse.text/src/org/eclipse/jface/text/Region.java b/org.eclipse.text/src/org/eclipse/jface/text/Region.java
index e09069e324c..7ca94e04581 100644
--- a/org.eclipse.text/src/org/eclipse/jface/text/Region.java
+++ b/org.eclipse.text/src/org/eclipse/jface/text/Region.java
@@ -34,14 +34,14 @@ public class Region implements IRegion {
 	}
 	
 	/*
-	 * @see IRegion#getLength
+	 * @see IRegion#getLength()
 	 */
 	public int getLength() {
 		return fLength;
 	}
 	
 	/*
-	 * @see IRegion#getOffset
+	 * @see IRegion#getOffset()
 	 */
 	public int getOffset() {
 		return fOffset;
@@ -50,7 +50,7 @@ public class Region implements IRegion {
 	/**
 	 * Two regions are equal if they have the same offset and length.
 	 *
-	 * @see Object#equals
+	 * @see Object#equals(Object)
 	 */
 	public boolean equals(Object o) {
 	 	if (o instanceof IRegion) {
@@ -61,7 +61,7 @@ public class Region implements IRegion {
 	}
 	 
 	/*
-	 * @see Object#hashCode
+	 * @see Object#hashCode()
 	 */
 	public int hashCode() {
 	 	return (fOffset << 24) | (fLength << 16);
diff --git a/org.eclipse.text/src/org/eclipse/jface/text/TextUtilities.java b/org.eclipse.text/src/org/eclipse/jface/text/TextUtilities.java
index b9e0920b7ab..46e838f6a69 100644
--- a/org.eclipse.text/src/org/eclipse/jface/text/TextUtilities.java
+++ b/org.eclipse.text/src/org/eclipse/jface/text/TextUtilities.java
@@ -21,13 +21,18 @@ import java.util.ListIterator;
  */
 public class TextUtilities {
 	
-	
+	/**
+	 * Default line delimiters used by these text functions.
+	 */
 	public final static String[] fgDelimiters= new String[] { "\n", "\r", "\r\n" }; //$NON-NLS-3$ //$NON-NLS-2$ //$NON-NLS-1$
 	
 	
 	/**
-	 * Determines which one of fgDelimiters appears first in the list. If none of them the
+	 * Determines which one of default line delimiters appears first in the list. If none of them the
 	 * hint is returned.
+	 * 
+	 * @param text the text to be checked
+	 * @param hint the line delimiter hint
 	 */
 	public static String determineLineDelimiter(String text, String hint) {
 		try {
@@ -39,8 +44,15 @@ public class TextUtilities {
 	}
 	
 	/**
-	 * Returns the position in the string greater than offset
-	 * of the longest matching search string.
+	 * Returns the starting position and the index of the longest matching search string
+	 * in the given text that is greater than the given offset. Returns <code>[-1, -1]</code>
+	 * if no match can be found.
+	 * 
+	 * @param searchStrings the strings to search for
+	 * @param text the text to be searched
+	 * @param offset the offset at which to start the search
+	 * @return an <code>int[]</code> with two elements" the first is the starting offset, the second the index of the found
+	 * 		search string in the given <code>searchStrings</code> array, returns <code>[-1, -1]</code> if no match exists
 	 */
 	public static int[] indexOf(String[] searchStrings, String text, int offset) {
 		
@@ -81,7 +93,12 @@ public class TextUtilities {
 	}
 	
 	/**
-	 * Returns the longest search string with which the given text ends.
+	 * Returns the index of the longest search string with which the given text ends or
+	 * <code>-1</code> if none matches.
+	 * 
+	 * @param searchStrings the strings to search for
+	 * @param text the text to search
+	 * @return the index in <code>searchStrings</code> of the longest string with which <code>text</code> ends or <code>-1</code>
 	 */
 	public static int endsWith(String[] searchStrings, String text) {
 		
@@ -98,7 +115,12 @@ public class TextUtilities {
 	}
 	
 	/**
-	 * Returns the longest search string with which the given text starts.
+	 * Returns the index of the longest search string with which the given text starts or <code>-1</code>
+	 * if none matches.
+	 * 
+	 * @param searchStrings the strings to search for
+	 * @param text the text to search
+	 * @return the index in <code>searchStrings</code> of the longest string with which <code>text</code> starts or <code>-1</code>
 	 */
 	public static int startsWith(String[] searchStrings, String text) {
 		
@@ -115,7 +137,12 @@ public class TextUtilities {
 	}
 	
 	/**
-	 * Returns whether the text equals one of the given compare strings.
+	 * Returns the index of the first compare string that equals the given text or <code>-1</code> 
+	 * if none is equal.
+	 * 
+	 * @param compareStrings the strings to compare with
+	 * @param text the text to check
+	 * @return the index of the first equal compare string or <code>-1</code>
 	 */
 	public static int equals(String[] compareStrings, String text) {
 		for (int i= 0; i < compareStrings.length; i++) {
diff --git a/org.eclipse.text/src/org/eclipse/jface/text/TypedRegion.java b/org.eclipse.text/src/org/eclipse/jface/text/TypedRegion.java
index f359214541e..bb4a451c0e0 100644
--- a/org.eclipse.text/src/org/eclipse/jface/text/TypedRegion.java
+++ b/org.eclipse.text/src/org/eclipse/jface/text/TypedRegion.java
@@ -42,7 +42,7 @@ public class TypedRegion extends Region implements ITypedRegion {
 	/**
 	 * Two typed positions are equal if they have the same offset, length, and type.
 	 *
-	 * @see Object#equals
+	 * @see Object#equals()
 	 */
 	public boolean equals(Object o) {
 		if (o instanceof TypedRegion) {
@@ -53,7 +53,7 @@ public class TypedRegion extends Region implements ITypedRegion {
 	}
 	
 	/*
-	 * @see Object#hashCode
+	 * @see Object#hashCode()
 	 */
 	 public int hashCode() {
 	 	int type= fType == null ? 0 : fType.hashCode();