Javadoc
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 bb18e30..d8ae620 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.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 @@
fProjectionCategory= projectionCategory;
}
- /* (non-Javadoc)
+ /*
* @see org.eclipse.jface.text.IDocumentInformationMapping#toOriginOffset(int)
*/
public int toOriginOffset(int imageOffset) throws BadLocationException {
@@ -46,7 +62,7 @@
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 @@
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 @@
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 @@
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 @@
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 @@
return null;
}
- /* (non-Javadoc)
+ /*
* @see org.eclipse.jface.text.IDocumentInformationMapping#toImageLine(int)
*/
public int toImageLine(int originLine) throws BadLocationException {
@@ -162,12 +184,30 @@
//-----------------------------------------------------------------------------------------------------------------------------------
-
+ /**
+ * 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 @@
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 @@
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 @@
return -1;
}
- /* (non-Javadoc)
+ /*
* @see org.eclipse.jface.text.IDocumentInformationMapping#getCoverage()
*/
public IRegion getCoverage() {
@@ -249,7 +310,7 @@
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 66ca92e..de6c5fb 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 @@
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 9f1dd6a..4b905f0 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 @@
/**
* 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 @@
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 @@
/**
* 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 @@
/**
* 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 @@
}
/*
- * @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 @@
//-------------------------------------------------------
/*
- * @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 @@
}
/*
- * @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 @@
}
/*
- * @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 @@
}
/*
- * @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 @@
}
/*
- * @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 @@
}
/*
- * @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 @@
}
/*
- * @see IDocument#addPositionCategory
+ * @see org.eclipse.jface.text.IDocument#addPositionCategory(java.lang.String)
*/
public void addPositionCategory(String category) {
@@ -313,14 +321,14 @@
}
/*
- * @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 @@
}
/*
- * @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 @@
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 @@
/**
* 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 @@
* 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 @@
* @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 @@
}
/*
- * @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 @@
}
/*
- * @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 @@
}
/*
- * @see IDocument#getLegalContentTypes
+ * @see IDocument#getLegalContentTypes()
*/
public String[] getLegalContentTypes() {
if (fDocumentPartitioner == null)
@@ -647,63 +657,63 @@
}
/*
- * @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 @@
}
/*
- * @see IDocument#getPartition
+ * @see IDocument#getPartition(int)
*/
public ITypedRegion getPartition(int offset) throws BadLocationException {
if ((0 > offset) || (offset > getLength()))
@@ -737,7 +747,7 @@
}
/*
- * @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 @@
}
/*
- * @see IDocument#getPositions
+ * @see IDocument#getPositions(String)
*/
public Position[] getPositions(String category) throws BadPositionCategoryException {
@@ -767,7 +777,7 @@
}
/*
- * @see IDocument#getPositionCategories
+ * @see IDocument#getPositionCategories()
*/
public String[] getPositionCategories() {
String[] categories= new String[fPositions.size()];
@@ -778,7 +788,7 @@
}
/*
- * @see IDocument#getPositionUpdaters
+ * @see IDocument#getPositionUpdaters()
*/
public IPositionUpdater[] getPositionUpdaters() {
IPositionUpdater[] updaters= new IPositionUpdater[fPositionUpdaters.size()];
@@ -787,14 +797,14 @@
}
/*
- * @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 @@
}
/*
- * @see IDocument#insertPositionUpdater
+ * @see IDocument#insertPositionUpdater(IPositionUpdater, int)
*/
public void insertPositionUpdater(IPositionUpdater updater, int index) {
@@ -820,7 +830,7 @@
}
/*
- * @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 @@
}
/*
- * @see IDocument#removePosition
+ * @see IDocument#removePosition(Position)
*/
public void removePosition(Position position) {
try {
@@ -855,7 +865,7 @@
}
/*
- * @see IDocument#removePositionCategory
+ * @see IDocument#removePositionCategory(String)
*/
public void removePositionCategory(String category) throws BadPositionCategoryException {
@@ -869,7 +879,7 @@
}
/*
- * @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 @@
}
/*
- * @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 @@
}
/*
- * @see IDocument#set
+ * @see IDocument#set(String)
*/
public void set(String text) {
int length= getStore().getLength();
@@ -928,7 +938,7 @@
}
/*
- * @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 @@
/**
* 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 @@
/*
* @see org.eclipse.jface.text.IDocumentExtension2#resumeListenerNotification()
+ * @since 2.1
*/
public void resumeListenerNotification() {
-- fStoppedListenerNotification;
@@ -1262,11 +1275,18 @@
/*
* @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 4ebc59a..aae1394 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 @@
}
/*
- * @see ILineTracker#getLineLength
+ * @see ILineTracker#getLineLength(int)
*/
public int getLineLength(int line) throws BadLocationException {
@@ -149,7 +149,7 @@
}
/*
- * @see ILineTracker#getLineNumberOfOffset
+ * @see ILineTracker#getLineNumberOfOffset(int)
*/
public int getLineNumberOfOffset(int position) throws BadLocationException {
@@ -170,7 +170,7 @@
}
/*
- * @see ILineTracker#getLineInformationOfOffset
+ * @see ILineTracker#getLineInformationOfOffset(int)
*/
public IRegion getLineInformationOfOffset(int position) throws BadLocationException {
if (position > fTextLength)
@@ -188,7 +188,7 @@
}
/*
- * @see ILineTracker#getLineInformation
+ * @see ILineTracker#getLineInformation(int)
*/
public IRegion getLineInformation(int line) throws BadLocationException {
@@ -210,7 +210,7 @@
}
/*
- * @see ILineTracker#getLineOffset
+ * @see ILineTracker#getLineOffset(int)
*/
public int getLineOffset(int line) throws BadLocationException {
@@ -232,7 +232,7 @@
}
/*
- * @see ILineTracker#getNumberOfLines
+ * @see ILineTracker#getNumberOfLines()
*/
public int getNumberOfLines() {
@@ -455,7 +455,7 @@
}
/*
- * @see ILineTracker#replace
+ * @see ILineTracker#replace(int, int, String)
*/
public void replace(int position, int length, String text) throws BadLocationException {
@@ -525,7 +525,7 @@
}
/*
- * @see ILineTracker#set
+ * @see ILineTracker#set(String)
*/
public void set(String text) {
fLines.clear();
@@ -536,7 +536,7 @@
}
/*
- * @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 1112c1b..40d65ab 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 @@
* </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.
+ * <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>
*/
- public AssertionFailedException(String detail) {
- super(detail);
+ 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() {
}
-/* 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 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$
}
- 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 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;
}
- 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 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;
+ }
+ isNotNull(object, "");//$NON-NLS-1$
}
- 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;
-}
+
+ /**
+ * 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;
+ }
+ 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 c46804e..7eb112f 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 @@
/**
- * 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 @@
/**
- * 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 @@
}
/*
- * @see ITextStore#replace
+ * @see ITextStore#replace(int, int, String)
*/
public void replace(int offset, int length, String txt) {
try {
@@ -52,14 +57,14 @@
}
/*
- * @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 @@
}
/*
- * @see ITextStore#get
+ * @see ITextStore#get(int)
*/
public char get(int offset) {
try {
@@ -88,16 +93,15 @@
/** 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 @@
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 @@
/**
* <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 @@
/**
* 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 @@
}
/*
- * @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 @@
/**
* 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 d2e5d3c..b7bc561 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 @@
/**
- * 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 @@
/**
- * 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 @@
*/
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 @@
}
}
}
-
+
+ /**
+ * 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 @@
*/
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 @@
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 @@
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 @@
}
}
- /* (non-Javadoc)
+ /*
* @see org.eclipse.jface.text.ISlaveDocumentManager#createMasterSlaveMapping(org.eclipse.jface.text.IDocument)
*/
public IDocumentInformationMapping createMasterSlaveMapping(IDocument slave) {
@@ -320,7 +343,7 @@
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 @@
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 edc806c..301b64c 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 @@
}
/*
- * @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 cc3683f..f7d68bb 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 @@
}
/*
- * @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 4daca7f..96bae42 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 @@
/** 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 f6eca84..b3fa42b 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 @@
/**
- * 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 50b6b33..e0946cb 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 @@
}
/*
- * @see ITextStore#get
+ * @see ITextStore#get(int)
*/
public char get(int offset) {
@@ -142,7 +142,7 @@
}
/*
- * @see ITextStore#get
+ * @see ITextStore#get(int, int)
*/
public String get(int offset, int length) {
@@ -166,7 +166,7 @@
}
/*
- * @see ITextStore#getLength
+ * @see ITextStore#getLength()
*/
public int getLength() {
int length= fGapEnd - fGapStart;
@@ -175,7 +175,7 @@
/*
- * @see ITextStore#replace
+ * @see ITextStore#replace(int, int, String)
*/
public void replace(int offset, int length, String text) {
@@ -214,7 +214,7 @@
* 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 9cdc5f7..c785a67 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 @@
* <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 f96728b..a7d636c 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 @@
/**
* 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 @@
/**
* 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 9549fed..837b845 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 @@
/**
* 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 4f82b5d..98e9d48 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 289f9fc..b11b23a 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 @@
/**
* 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 160b1a7..4016f59 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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
return null;
}
- /* (non-Javadoc)
+ /*
* @see org.eclipse.jface.text.IDocumentInformationMapping#toImageLine(int)
*/
public int toImageLine(int originLine) throws BadLocationException {
@@ -129,7 +139,7 @@
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 85bb12a..b11a53e 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 @@
/**
- * 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 @@
}
/*
- * @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 e09069e..7ca94e0 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 @@
}
/*
- * @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 @@
/**
* 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 @@
}
/*
- * @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 b9e0920..46e838f 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 @@
*/
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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 f359214..bb4a451 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 @@
/**
* 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 @@
}
/*
- * @see Object#hashCode
+ * @see Object#hashCode()
*/
public int hashCode() {
int type= fType == null ? 0 : fType.hashCode();
