updated Javadoc

32 files changed, 399 insertions, 193 deletions

diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/AnnotationBarHoverManager.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/AnnotationBarHoverManager.java
index 0bdbd1b8640..ad5e8a98bb4 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/AnnotationBarHoverManager.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/AnnotationBarHoverManager.java
@@ -268,7 +268,7 @@ public class AnnotationBarHoverManager extends AbstractHoverInformationControlMa
 	}	
 	
 	/*
-	 * @see AbstractHoverInformationControlManager#computeInformation()
+	 * @see org.eclipse.jface.text.AbstractInformationControlManager#computeInformation()
 	 */
 	protected void computeInformation() {
 		fAllowMouseExit= false;
@@ -294,6 +294,16 @@ public class AnnotationBarHoverManager extends AbstractHoverInformationControlMa
 			
 	}
 	
+	/**
+	 * Adapts a given line range so that the result is a line range that does
+	 * not overlap with any collapsed region and fits into the view port of the
+	 * attached viewer.
+	 * 
+	 * @param lineRange the original line range
+	 * @param line the anchor line
+	 * @return the adapted line range
+	 * @since 3.0
+	 */
 	private ILineRange adaptLineRange(ILineRange lineRange, int line) {
 		if (lineRange != null) {
 			lineRange= adaptLineRangeToFolding(lineRange, line);
@@ -303,6 +313,15 @@ public class AnnotationBarHoverManager extends AbstractHoverInformationControlMa
 		return null;
 	}
 	
+	/**
+	 * Adapts a given line range so that the result is a line range that does
+	 * not overlap with any collapsed region of the attached viewer.
+	 * 
+	 * @param lineRange the original line range
+	 * @param line the anchor line
+	 * @return the adapted line range
+	 * @since 3.0
+	 */
 	private ILineRange adaptLineRangeToFolding(ILineRange lineRange, int line) {
 				
 		if (fSourceViewer instanceof ITextViewerExtension5) {
@@ -326,6 +345,14 @@ public class AnnotationBarHoverManager extends AbstractHoverInformationControlMa
 		return lineRange;	
 	}
 	
+	/**
+	 * Adapts a given line range so that the result is a line range that fits
+	 * into the view port of the attached viewer.
+	 * 
+	 * @param lineRange the original line range
+	 * @return the adapted line range
+	 * @since 3.0
+	 */
 	private ILineRange adaptLineRangeToViewport(ILineRange lineRange) {
 		
 		try {
@@ -352,6 +379,13 @@ public class AnnotationBarHoverManager extends AbstractHoverInformationControlMa
 		return null;
 	}
 	
+	/**
+	 * Converts a line range into a character range.
+	 * 
+	 * @param lineRange the line range
+	 * @return the corresponding character range
+	 * @throws BadLocationException in case the given line range is invalid
+	 */
 	private IRegion convertToRegion(ILineRange lineRange) throws BadLocationException {
 		IDocument document= fSourceViewer.getDocument();
 		int startOffset= document.getLineOffset(lineRange.getStartLine());
@@ -361,6 +395,15 @@ public class AnnotationBarHoverManager extends AbstractHoverInformationControlMa
 		return new Region(startOffset, endOffset - startOffset);
 	}
 	
+	/**
+	 * Returns the region out of the given set that contains the given line or
+	 * <code>null</code>.
+	 * 
+	 * @param regions the set of regions
+	 * @param line the line
+	 * @return the region of the set that contains the line
+	 * @throws BadLocationException in case line is invalid
+	 */
 	private IRegion findRegionContainingLine(IRegion[] regions, int line) throws BadLocationException {
 		IDocument document= fSourceViewer.getDocument();
 		IRegion lineInfo= document.getLineInformation(line);
@@ -370,7 +413,14 @@ public class AnnotationBarHoverManager extends AbstractHoverInformationControlMa
 		}
 		return null;
 	}
-
+	
+	/**
+	 * Converts a given character region into a line range.
+	 * 
+	 * @param region the character region
+	 * @return the corresponding line range
+	 * @throws BadLocationException in case the given region in invalid
+	 */
 	private ILineRange convertToLineRange(IRegion region) throws BadLocationException {
 		IDocument document= fSourceViewer.getDocument();
 		int startLine= document.getLineOfOffset(region.getOffset());
@@ -378,6 +428,13 @@ public class AnnotationBarHoverManager extends AbstractHoverInformationControlMa
 		return new LineRange(startLine, endLine - startLine + 1);
 	}
 	
+	/**
+	 * Returns the visible area of the vertical ruler covered by the given line
+	 * range.
+	 * 
+	 * @param lineRange the line range
+	 * @return the visible area
+	 */
 	private Rectangle computeArea(ILineRange lineRange) {
 		try {
 			StyledText text= fSourceViewer.getTextWidget();
@@ -390,6 +447,11 @@ public class AnnotationBarHoverManager extends AbstractHoverInformationControlMa
 		return null;
 	}
 	
+	/**
+	 * Returns the number of the currently visible lines.
+	 * 
+	 * @return the number of the currently visible lines
+	 */
 	private int computeNumberOfVisibleLines() {
 		StyledText text= fSourceViewer.getTextWidget();
 		Point size= fVerticalRulerInfo.getControl().getSize();
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/AnnotationColumn.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/AnnotationColumn.java
index e021ffd3dc0..43136666d9b 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/AnnotationColumn.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/AnnotationColumn.java
@@ -13,7 +13,7 @@ package org.eclipse.jface.text.source;
 
 
 /**
- * @deprecated use <code>AnnotationRulerColumn</code> instead.
+ * @deprecated use {@link org.eclipse.jface.text.source.AnnotationRulerColumn} instead.
  * @since 2.0
  */
 public final class AnnotationColumn extends AnnotationRulerColumn {
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/AnnotationPainter.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/AnnotationPainter.java
index 0636af3ad76..381588046e9 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/AnnotationPainter.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/AnnotationPainter.java
@@ -8,7 +8,6 @@
  * Contributors:
  *     IBM Corporation - initial API and implementation
  *******************************************************************************/
-
 package org.eclipse.jface.text.source;
 
 
@@ -45,8 +44,14 @@ import org.eclipse.jface.text.TextPresentation;
 
 
 /**
- * Paints annotations provided by an annotation model as squiggly lines and/or
- * highlighted onto an associated source viewer.
+ * Paints decorations for annotations provided by an annotation model and/or
+ * highlights them in the associated source viewer.
+ * <p>
+ * The annotation painter can be configured with drawing strategies. A drawing
+ * strategy defines the visual presentation of a particular type of annotation
+ * decoration.
+ * <p>
+ * 
  * Clients usually instantiate and configure objects of this class.
  * 
  * @since 2.1
@@ -155,6 +160,7 @@ public class AnnotationPainter implements IPainter, PaintListener, IAnnotationMo
 	
 	/**
 	 * Drawing strategy that does nothing.
+	 * 
 	 * @since 3.0
 	 */
 	public static final class NullStrategy implements IDrawingStrategy {
@@ -324,21 +330,21 @@ public class AnnotationPainter implements IPainter, PaintListener, IAnnotationMo
 	 */
 	private boolean fInputDocumentAboutToBeChanged;
 	/**
-	 * Maps annotation types to drawing strategy ids.
+	 * Maps annotation types to drawing strategy identifiers.
 	 * @since 3.0
 	 */
 	private Map fAnnotationType2DrawingStrategyId= new HashMap();
 	/**
-	 * Maps drawing strategy ids to drawing strategies.
+	 * Maps drawing strategy identifiers to drawing strategies.
 	 * @since 3.0
 	 */
 	private Map fRegisteredDrawingStrategies= new HashMap();
 	
 	
 	/**
-	 * Creates a new annotation painter for the given source viewer and with the given
-	 * annotation access. The painter is uninitialized, i.e.  no annotation types are configured
-	 * to be painted.
+	 * Creates a new annotation painter for the given source viewer and with the
+	 * given annotation access. The painter is not initialized, i.e. no
+	 * annotation types are configured to be painted.
 	 * 
 	 * @param sourceViewer the source viewer for this painter
 	 * @param access the annotation access for this painter
@@ -348,7 +354,7 @@ public class AnnotationPainter implements IPainter, PaintListener, IAnnotationMo
 		fAnnotationAccess= access;
 		fTextWidget= sourceViewer.getTextWidget();
 		
-		// default drawing strategies: squiggles are the only pre-3.0 drawing style,
+		// default drawing strategies: squiggles were the only decoration style before version 3.0
 		fRegisteredDrawingStrategies.put(SQUIGGLES, fgSquigglyDrawer);
 	}
 	
@@ -822,7 +828,7 @@ public class AnnotationPainter implements IPainter, PaintListener, IAnnotationMo
 	}
 
 	/*
-	 * @see ITextPresentationListener#applyTextPresentation(TextPresentation)
+	 * @see org.eclipse.jface.text.ITextPresentationListener#applyTextPresentation(org.eclipse.jface.text.TextPresentation)
 	 * @since 3.0
 	 */
 	public void applyTextPresentation(TextPresentation tp) {
@@ -877,7 +883,7 @@ public class AnnotationPainter implements IPainter, PaintListener, IAnnotationMo
 	}
 
 	/*
-	 * @see IAnnotationModelListener#modelChanged(IAnnotationModel)
+	 * @see org.eclipse.jface.text.source.IAnnotationModelListener#modelChanged(org.eclipse.jface.text.source.IAnnotationModel)
 	 */
 	public synchronized void modelChanged(final IAnnotationModel model) {
 		if (DEBUG)
@@ -887,7 +893,7 @@ public class AnnotationPainter implements IPainter, PaintListener, IAnnotationMo
 	}
 	
 	/*
-	 * @see IAnnotationModelListenerExtension#modelChanged(AnnotationModelEvent)
+	 * @see org.eclipse.jface.text.source.IAnnotationModelListenerExtension#modelChanged(org.eclipse.jface.text.source.AnnotationModelEvent)
 	 */
 	public void modelChanged(final AnnotationModelEvent event) {
 		if (fTextWidget != null && !fTextWidget.isDisposed()) {
@@ -1071,7 +1077,7 @@ public class AnnotationPainter implements IPainter, PaintListener, IAnnotationMo
 	}
 	
 	/*
-	 * @see IPainter#dispose()
+	 * @see org.eclipse.jface.text.IPainter#dispose()
 	 */
 	public void dispose() {
 		
@@ -1108,10 +1114,10 @@ public class AnnotationPainter implements IPainter, PaintListener, IAnnotationMo
 	}
 
 	/**
-	 * Returns the document offset of the upper left corner of the source viewer's viewport,
+	 * Returns the document offset of the upper left corner of the source viewer's view port,
 	 * possibly including partially visible lines.
 	 * 
-	 * @return the document offset if the upper left corner of the viewport
+	 * @return the document offset if the upper left corner of the view port
 	 */
 	private int getInclusiveTopIndexStartOffset() {
 		
@@ -1140,10 +1146,10 @@ public class AnnotationPainter implements IPainter, PaintListener, IAnnotationMo
 	}
 	
 	/**
-	 * Returns the first invisible document offset of the lower right corner of the source viewer's viewport,
+	 * Returns the first invisible document offset of the lower right corner of the source viewer's view port,
 	 * possibly including partially visible lines.
 	 * 
-	 * @return the first invisible document offset of the lower right corner of the viewport
+	 * @return the first invisible document offset of the lower right corner of the view port
 	 */
 	private int getExclusiveBottomIndexEndOffset() {
 		
@@ -1166,7 +1172,7 @@ public class AnnotationPainter implements IPainter, PaintListener, IAnnotationMo
 	}
 	
 	/*
-	 * @see PaintListener#paintControl(PaintEvent)
+	 * @see org.eclipse.swt.events.PaintListener#paintControl(org.eclipse.swt.events.PaintEvent)
 	 */
 	public void paintControl(PaintEvent event) {
 		if (fTextWidget != null)
@@ -1332,7 +1338,7 @@ public class AnnotationPainter implements IPainter, PaintListener, IAnnotationMo
 	}
 	
 	/*
-	 * @see IPainter#deactivate(boolean)
+	 * @see org.eclipse.jface.text.IPainter#deactivate(boolean)
 	 */
 	public void deactivate(boolean redraw) {
 		if (fIsActive) {
@@ -1368,7 +1374,7 @@ public class AnnotationPainter implements IPainter, PaintListener, IAnnotationMo
 	}
 	
 	/*
-	 * @see IPainter#paint(int)
+	 * @see org.eclipse.jface.text.IPainter#paint(int)
 	 */
 	public void paint(int reason) {
 		if (fSourceViewer.getDocument() == null) {
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/AnnotationRulerColumn.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/AnnotationRulerColumn.java
index 355d9dc0faf..1809b9d62ed 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/AnnotationRulerColumn.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/AnnotationRulerColumn.java
@@ -8,7 +8,6 @@
  * Contributors:
  *     IBM Corporation - initial API and implementation
  *******************************************************************************/
-
 package org.eclipse.jface.text.source;
 
 
@@ -55,8 +54,9 @@ import org.eclipse.jface.text.TextViewer;
 
 
 /**
- * A vertical ruler column showing graphical representations of  annotations.
+ * A vertical ruler column showing graphical representations of annotations.
  * Will become final. Do not subclass.
+ * 
  * @since 2.0
  */
 public class AnnotationRulerColumn implements IVerticalRulerColumn, IVerticalRulerInfo, IVerticalRulerInfoExtension {
@@ -167,7 +167,7 @@ public class AnnotationRulerColumn implements IVerticalRulerColumn, IVerticalRul
 	private IAnnotationModel fModel;
 	/** Cache for the actual scroll position in pixels */
 	private int fScrollPos;
-	/** The drawable for double buffering */
+	/** The buffer for double buffering */
 	private Image fBuffer;
 	/** The internal listener */
 	private InternalListener fInternalListener= new InternalListener();
@@ -365,6 +365,12 @@ public class AnnotationRulerColumn implements IVerticalRulerColumn, IVerticalRul
 		return fCanvas;
 	}
 	
+	/**
+	 * Creates a canvas with the given parent.
+	 * 
+	 * @param parent the parent 
+	 * @return the created canvas
+	 */
 	private Canvas createCanvas(Composite parent) {
 		return new Canvas(parent, SWT.NO_BACKGROUND) {
 			/*
@@ -538,7 +544,7 @@ public class AnnotationRulerColumn implements IVerticalRulerColumn, IVerticalRul
 
 	/**
 	 * Returns the document offset of the upper left corner of the source viewer's
-	 * viewport, possibly including partially visible lines.
+	 * view port, possibly including partially visible lines.
 	 * 
 	 * @return document offset of the upper left corner including partially visible lines
 	 */
@@ -569,10 +575,10 @@ public class AnnotationRulerColumn implements IVerticalRulerColumn, IVerticalRul
 	}
 	
 	/**
-	 * Returns the first invisible document offset of the lower right corner of the source viewer's viewport,
+	 * Returns the first invisible document offset of the lower right corner of the source viewer's view port,
 	 * possibly including partially visible lines.
 	 * 
-	 * @return the first invisible document offset of the lower right corner of the viewport
+	 * @return the first invisible document offset of the lower right corner of the view port
 	 */
 	private int getExclusiveBottomIndexEndOffset() {
 		
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ChangeRulerColumn.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ChangeRulerColumn.java
index df44274e240..35697dc2ce5 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ChangeRulerColumn.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ChangeRulerColumn.java
@@ -130,7 +130,7 @@ public final class ChangeRulerColumn implements IVerticalRulerColumn, IVerticalR
 	private Canvas fCanvas;
 	/** Cache for the actual scroll position in pixels */
 	private int fScrollPos;
-	/** The drawable for double buffering */
+	/** The buffer for double buffering */
 	private Image fBuffer;
 	/** The internal listener */
 	private InternalListener fInternalListener= new InternalListener();
@@ -276,9 +276,9 @@ public final class ChangeRulerColumn implements IVerticalRulerColumn, IVerticalR
 	}
 	
 	/**
-	 * Returns the viewport height in lines.
+	 * Returns the view port height in lines.
 	 *
-	 * @return the viewport height in lines
+	 * @return the view port height in lines
 	 */
 	protected int getVisibleLinesInViewport() {
 		Rectangle clArea= fCachedTextWidget.getClientArea();
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/CompositeRuler.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/CompositeRuler.java
index f0c9f0f87f2..b5ecf0be814 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/CompositeRuler.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/CompositeRuler.java
@@ -8,7 +8,6 @@
  * Contributors:
  *     IBM Corporation - initial API and implementation
  *******************************************************************************/
-
 package org.eclipse.jface.text.source;
 
 
@@ -54,21 +53,25 @@ import org.eclipse.jface.text.ITextViewerExtension5;
 
 
 /**
- * Standard implementation of <code>IVerticalRuler</code>. This ruler does not have a 
- * a visual representation of its own.  The presentation comes from the configurable list 
- * of decorators. Decorators must implement the <code>IVerticalRulerColumn</code>
- * interface.<p>
+ * Standard implementation of
+ * {@link org.eclipse.jface.text.source.IVerticalRuler}.
+ * <p>
+ * This ruler does not have a a visual representation of its own. The
+ * presentation comes from the configurable list of vertical ruler columns. Such
+ * columns must implement the
+ * {@link org.eclipse.jface.text.source.IVerticalRulerColumn}. interface.
+ * <p>
  * Clients may instantiate and configure this class.
- *
- * @see IVerticalRulerColumn
- * @see ITextViewer
+ * 
+ * @see org.eclipse.jface.text.source.IVerticalRulerColumn
+ * @see org.eclipse.jface.text.ITextViewer
  * @since 2.0
  */
 public class CompositeRuler implements IVerticalRuler, IVerticalRulerExtension, IVerticalRulerInfoExtension {
 	
 	
 	/**
-	 * Layout of the composite vertical ruler. Arranges the list of decorators.
+	 * Layout of the composite vertical ruler. Arranges the list of columns.
 	 */
 	class RulerLayout extends Layout {
 		
@@ -214,7 +217,7 @@ public class CompositeRuler implements IVerticalRuler, IVerticalRulerExtension,
 		}
 		
 		/**
-		 * Removes the given listener object as listner of the given type (<code>clazz</code>) from
+		 * Removes the given listener object as listener of the given type (<code>clazz</code>) from
 		 * the given control.
 		 * 
 		 * @param clazz the listener type
@@ -507,7 +510,7 @@ public class CompositeRuler implements IVerticalRuler, IVerticalRulerExtension,
 	private CompositeRulerCanvas fComposite;
 	/** The ruler's annotation model */
 	private IAnnotationModel fModel;
-	/** The list of decorators */
+	/** The list of columns */
 	private List fDecorators= new ArrayList(2);
 	/** The cached location of the last mouse button activity */
 	private Point fLocation= new Point(-1, -1);
@@ -539,8 +542,8 @@ public class CompositeRuler implements IVerticalRuler, IVerticalRulerExtension,
 	}
 	
 	/**
-	 * Inserts the given decorator at the specfied slot to this composite ruler.
-	 * Decorators are counted from left to right.
+	 * Inserts the given column at the specified slot to this composite ruler.
+	 * Columns are counted from left to right.
 	 * 
 	 * @param index the index
 	 * @param rulerColumn the decorator to be inserted
@@ -587,8 +590,8 @@ public class CompositeRuler implements IVerticalRuler, IVerticalRulerExtension,
 	}
 
 	/**
-	 * Relayouts the text viewer. This also causes this ruler to get
-	 * relayouted.
+	 * Layouts the text viewer. This also causes this ruler to get
+	 * be layouted.
 	 */
 	private void layoutTextViewer() {
 		
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IAnnotationAccess.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IAnnotationAccess.java
index d666c6b296f..03c34bee87c 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IAnnotationAccess.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IAnnotationAccess.java
@@ -11,9 +11,22 @@
 package org.eclipse.jface.text.source;
 
 /**
- * An annotation access provides access to information that is not available via the
- * API of <code>Annotation</code>. Clients usually implement this interface. 
+ * An annotation access provides access to information that is not available via
+ * the API of {@link org.eclipse.jface.text.source.Annotation}. With version
+ * 3.0 all this information is now available from the annotation itself.
+ * <p>
  * 
+ * In order to provide backward compatibility for clients of
+ * <code>IAnnotationAccess</code>, extension interfaces are used as a means
+ * of evolution. The following extension interfaces exist:
+ * <ul>
+ * <li>{@link org.eclipse.jface.text.source.IAnnotationAccessExtension}since
+ *     version 3.0 replacing all methods in that interface</li>
+ * </ul>
+ * <p>
+ * Clients usually implement this interface and its extension interfaces.
+ * 
+ * @see org.eclipse.jface.text.source.IAnnotationAccessExtension
  * @see org.eclipse.jface.text.source.Annotation
  * @since 2.1
  */
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IAnnotationAccessExtension.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IAnnotationAccessExtension.java
index c4e7c10c2a5..696c0b2d78b 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IAnnotationAccessExtension.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IAnnotationAccessExtension.java
@@ -8,7 +8,6 @@
  * Contributors:
  *     IBM Corporation - initial API and implementation
  *******************************************************************************/
-
 package org.eclipse.jface.text.source;
 
 import org.eclipse.swt.graphics.GC;
@@ -16,10 +15,17 @@ import org.eclipse.swt.graphics.Rectangle;
 import org.eclipse.swt.widgets.Canvas;
 
 /**
- * Extension interface for <code>IAnnotationAccess</code>.
- * Allows to get a label for the annotation's type.
- * </code>.
+ * Extension interface for {@link org.eclipse.jface.text.source.IAnnotationAccess}.<p>
+ * This interface replaces the methods of <code>IAnnotationAccess</code>.<p>
+ * This interface provides
+ * <ul>
+ * <li> a label for the annotation type of a given annotation</li>
+ * <li> the paint layer of a given annotation</li>
+ * <li> means to paint a given annotation</li>
+ * <li> information about the type hierarchy of the annotation type of a given annotation</li>
+ * <ul>.
  * 
+ * @see org.eclipse.jface.text.source.IAnnotationAccess
  * @since 3.0
  */
 public interface IAnnotationAccessExtension {
@@ -62,7 +68,7 @@ public interface IAnnotationAccessExtension {
 	 * Returns <code>true</code> if painting <code>annotation</code> will produce something
 	 * meaningful, <code>false</code> if not. E.g. if no image is available.
 	 * 
-	 * @param annotation the annotation to check for paintability
+	 * @param annotation the annotation to check whether it can be painted
 	 * @return <code>true</code> if painting <code>annotation</code> will succeed
 	 */
 	boolean isPaintable(Annotation annotation);
@@ -73,7 +79,7 @@ public interface IAnnotationAccessExtension {
 	 * 
 	 * @param annotationType the annotation type
 	 * @param potentialSupertype the potential super annotation type
-	 * @return <code>true</code> if annotation type is a subtype of the potential annotation super type
+	 * @return <code>true</code> if annotation type is a sub-type of the potential annotation super type
 	 */
 	boolean isSubtype(Object annotationType, Object potentialSupertype);
 	
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IAnnotationHover.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IAnnotationHover.java
index 885c099e200..af57cd17dae 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IAnnotationHover.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IAnnotationHover.java
@@ -12,11 +12,23 @@ package org.eclipse.jface.text.source;
 
 
 
-
 /**
- * Provides the information to be displayed in a hover popup window
- * which appears over the presentation area of annotations. Clients
- * may implement this interface.
+ * Provides the information to be displayed in a hover popup window which
+ * appears over the presentation area of annotations.
+ * <p>
+ * In order to provide backward compatibility for clients of
+ * <code>IAnnotationHover</code>, extension interfaces are used as a means of
+ * evolution. The following extension interfaces exist:
+ * <ul>
+ * <li>{@link org.eclipse.jface.text.source.IAnnotationHoverExtension}since
+ *     version 3.0 allowing a text hover to provide a creator for the hover control.
+ *     This allows for sophisticated hovers in a way that information computed by
+ *     the hover can be displayed in the best possible form.</li>
+ * </ul>
+ * <p>
+ * Clients may implement this interface.
+ * 
+ * @see org.eclipse.jface.text.source.IAnnotationHoverExtension
  */
 public interface IAnnotationHover {
 		
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IAnnotationHoverExtension.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IAnnotationHoverExtension.java
index 6a50ebb766d..0ba8d57f642 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IAnnotationHoverExtension.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IAnnotationHoverExtension.java
@@ -13,7 +13,7 @@ package org.eclipse.jface.text.source;
 import org.eclipse.jface.text.IInformationControlCreator;
 
 /**
- * Extension to <code>IAnnotationHover</code> for
+ * Extension interface for {@link org.eclipse.jface.text.source.IAnnotationHover} for
  * <ul>
  * <li>providing its own information control creator</li>
  * <li>providing the range of lines for which the hover for a given line is valid</li>
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IAnnotationPresentation.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IAnnotationPresentation.java
index 784662ffc00..810ae0447e1 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IAnnotationPresentation.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IAnnotationPresentation.java
@@ -15,7 +15,7 @@ import org.eclipse.swt.graphics.Rectangle;
 import org.eclipse.swt.widgets.Canvas;
 
 /**
- * Interface for annotations that know how to represent themselves.
+ * Interface for annotations that can take care of their own visible representation.
  *
  * @since 3.0
  */
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ICharacterPairMatcher.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ICharacterPairMatcher.java
index d999f67679e..417ca4d957e 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ICharacterPairMatcher.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ICharacterPairMatcher.java
@@ -14,12 +14,14 @@ import org.eclipse.jface.text.IDocument;
 import org.eclipse.jface.text.IRegion;
 
 /**
- * A character pair matcher finds to a character at a certain document offset the matching peer character.
- * It is the matchers responsibility to define the concepts of "matching" and "peer". The matching process 
- * starts at a given offset. Starting of this offset, the matcher chooses a character close to this offset. The
- * anchor defines whether the chosen character is left or right of the initial offset. The matcher then searches
- * for the matching peer character of the chosen character and if it finds one, delivers the minimal region of
- * the document that contains both characters.
+ * A character pair matcher finds to a character at a certain document offset
+ * the matching peer character. It is the matchers responsibility to define the
+ * concepts of "matching" and "peer". The matching process starts at a given
+ * offset. Starting of this offset, the matcher chooses a character close to
+ * this offset. The anchor defines whether the chosen character is left or right
+ * of the initial offset. The matcher then searches for the matching peer
+ * character of the chosen character and if it finds one, delivers the minimal
+ * region of the document that contains both characters.
  * 
  * @since 2.1
  */
@@ -55,7 +57,7 @@ public interface ICharacterPairMatcher {
 	 * 
 	 * @param iDocument the document to work on
 	 * @param i the start offset
-	 * @return the minimal region containg the peer characters
+	 * @return the minimal region containing the peer characters
 	 */
 	IRegion match(IDocument iDocument, int i);
 
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ILineRange.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ILineRange.java
index c14d22acc5b..f37116bba23 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ILineRange.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ILineRange.java
@@ -11,19 +11,21 @@
 package org.eclipse.jface.text.source;
 
 /**
+ * Describes a range of lines.
+ * 
  * @since 3.0
  */
 public interface ILineRange {
 
 	/**
-	 * Returns the start line of this line range.
+	 * Returns the start line of this line range or <code>-1</code>.
 	 * 
 	 * @return the start line of this line range or <code>-1</code> if this line range is invalid.
 	 */
 	int getStartLine();
 
 	/**
-	 * Returns the number of lines of this line range.
+	 * Returns the number of lines of this line range or <code>-1</code>.
 	 * 
 	 * @return the number of lines in this line range or <code>-1</code> if this line range is invalid.
 	 */
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IOverviewRuler.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IOverviewRuler.java
index cdd70424bbf..5c93f47969f 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IOverviewRuler.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IOverviewRuler.java
@@ -16,11 +16,11 @@ import org.eclipse.swt.widgets.Control;
 /**
  * This interface defines a visual component which may serve
  * text viewers as an overview annotation presentation area.  This means,
- * presentation of annotations is independent from the actual viewport of
+ * presentation of annotations is independent from the actual view port of
  * the text viewer. The annotations of the viewer's whole document are 
  * visible in the overview ruler.
  * 
- * This interfaces comprises three contracts:
+ * This interfaces embodies three contracts:
  * <ul>
  * <li>	The overview ruler retrieves the annotations it presents from an annotation model.
  * <li>	The ruler is a visual component which must be integrated in a hierarchy of SWT controls.
@@ -38,7 +38,7 @@ import org.eclipse.swt.widgets.Control;
 public interface IOverviewRuler extends IVerticalRuler {
 	
 	/**
-	 * Returns whether there is an annotation an the given y coordinate. This
+	 * Returns whether there is an annotation an the given vertical coordinate. This
 	 * method takes the compression factor of the overview ruler into account.
 	 * 
 	 * @param y the y-coordinate
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ISharedTextColors.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ISharedTextColors.java
index 13ac9b1d6ea..16bea841b34 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ISharedTextColors.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ISharedTextColors.java
@@ -17,7 +17,9 @@ import org.eclipse.swt.graphics.RGB;
 /**
  * Manages SWT color objects. Until the <code>dispose</code> method is called,
  * the same color object is returned for equal <code>RGB</code> values.
- * <p> This interface may be implemented by clients. </p>
+ * <p>
+ * This interface may be implemented by clients.
+ * </p>
  * 
  * @since 2.1
  */
@@ -27,8 +29,8 @@ public interface ISharedTextColors {
 	 * Returns the color object for the value represented by the given
 	 * <code>RGB</code> object.
 	 *
-	 * @param rgb the rgb color specification
-	 * @return the color object for the given rgb value
+	 * @param rgb the RBG color specification
+	 * @return the color object for the given RGB value
 	 */
 	Color getColor(RGB rgb);	
 	
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ISourceViewer.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ISourceViewer.java
index 16a1c30c720..45b89f977a1 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ISourceViewer.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ISourceViewer.java
@@ -21,19 +21,36 @@ import org.eclipse.jface.text.ITextViewer;
 /**
  * In addition to the text viewer functionality a source viewer supports:
  * <ul>
- * <li> visual annotations based on an annotation model
- * <li> visual range indication
- * <li> management of text viewer add-ons
- * <li> explicit configuration
+ * <li>visual annotations based on an annotation model
+ * <li>visual range indication
+ * <li>management of text viewer add-ons
+ * <li>explicit configuration
  * </ul>
- * It is assumed that range indication and visual annotations are shown
- * inside the same presentation area. There are no assumptions about 
- * whether this area is different from the viewer's text widget.<p>
- * As the visibility of visual annotations can dynamically be changed, 
- * it is assumed that the annotation presentation area can dynamically 
- * be hidden if it is different from the text widget.<p>
- * Clients may implement this interface or use the default implementation provided
- * by <code>SourceViewer</code>.
+ * It is assumed that range indication and visual annotations are shown inside
+ * the same presentation area. There are no assumptions about whether this area
+ * is different from the viewer's text widget.
+ * <p>
+ * As the visibility of visual annotations can dynamically be changed, it is
+ * assumed that the annotation presentation area can dynamically be hidden if it
+ * is different from the text widget.
+ * <p>
+ * In order to provide backward compatibility for clients of
+ * <code>ISourceViewer</code>, extension interfaces are used as a means of
+ * evolution. The following extension interfaces exist:
+ * <ul>
+ * <li>{@link org.eclipse.jface.text.source.ISourceViewerExtension} since version 2.1
+ * introducing the concept of an annotation overview.</li>
+ * <li>{@link org.eclipse.jface.text.source.ISourceViewerExtension2} since version 3.0
+ * allowing source viewers to roll back a previously performed configuration and
+ * allows access to the viewer's visual annotation model.</li>
+ * </ul>
+ * <p>
+ * Clients may implement this interface and its extension interfaces or use the
+ * default implementation provided by
+ * {@link org.eclipse.jface.text.source.SourceViewer}.
+ * 
+ * @see org.eclipse.jface.text.source.ISourceViewerExtension
+ * @see org.eclipse.jface.text.source.ISourceViewerExtension2
  */
 public interface ISourceViewer extends ITextViewer {
 	
@@ -113,8 +130,10 @@ public interface ISourceViewer extends ITextViewer {
 	void setDocument(IDocument document, IAnnotationModel annotationModel, int modelRangeOffset, int modelRangeLength);
 	
 	/**
-	 * Returns this viewer's annotation model.
-	 *
+	 * Returns this viewer's annotation model. Use
+	 * {@link ISourceViewerExtension2#getVisualAnnotationModel()}in order to
+	 * get access to the viewer's visual annotation model.
+	 * 
 	 * @return this viewer's annotation model
 	 */
 	IAnnotationModel getAnnotationModel();
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ISourceViewerExtension.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ISourceViewerExtension.java
index db4b8598d35..8ba8973d726 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ISourceViewerExtension.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ISourceViewerExtension.java
@@ -12,18 +12,19 @@
 package org.eclipse.jface.text.source;
 
 /**
- * Extension interface for <code>ISourceViewer</code>.
- * Extends the source viewer with the concept of an annotation overview.
- * The annotation overview differs from the annotation presentation in that it is
- * independent from the viewer's view port, i.e. the annotations of the 
- * whole document are visible. There are no assumptions about 
- * the area in which the annotation overview is shown.<p>
- * As the visibility of annotation overview can dynamically be changed, 
- * it is assumed that the presentation area can dynamically 
- * be hidden if it is different from the text widget.<p>
- * Clients may implement this interface or use the default implementation provided
- * by <code>SourceViewer</code>.
+ * Extension interface {@link org.eclipse.jface.text.source.ISourceViewer}.
+ * <p>
+ * Extends the source viewer with the concept of an annotation overview. The
+ * annotation overview differs from the annotation presentation in that it is
+ * independent from the viewer's view port, i.e. the annotations of the whole
+ * document are visible. There are no assumptions about the area in which the
+ * annotation overview is shown.
+ * <p>
+ * As the visibility of annotation overview can dynamically be changed, it is
+ * assumed that the presentation area can dynamically be hidden if it is
+ * different from the text widget.
  * 
+ * @see org.eclipse.jface.text.source.ISourceViewer
  * @since 2.1
  */
 public interface ISourceViewerExtension {
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ISourceViewerExtension2.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ISourceViewerExtension2.java
index 434035bbcd9..8c303dedc57 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ISourceViewerExtension2.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ISourceViewerExtension2.java
@@ -12,18 +12,19 @@
 package org.eclipse.jface.text.source;
 
 /**
- * Extension interface for {@link ISourceViewer}.
- * Extends the source viewer with the functionality of explicit
- * unconfiguration.
+ * Extension interface for {@link org.eclipse.jface.text.source.ISourceViewer}.<p>
+ * Allows the source viewer to roll back a previous configuration process and allows
+ * clients access to the viewer's visual annotation model.
  * 
  * @since 3.0
  */
 public interface ISourceViewerExtension2 {
 	
 	/**
-	 * Unconfigures this source viewer. The source viewer can be configured again
-	 * after a call to this method. Unlike {@link ISourceViewer#configure(SourceViewerConfiguration)}
-	 * this method can be called more than once without interleaving calls to
+	 * Rolls back the configuration process of this source viewer. The source
+	 * viewer can be configured again after a call to this method. Unlike
+	 * {@link ISourceViewer#configure(SourceViewerConfiguration)} this method
+	 * can be called more than once without interleaving calls to
 	 * {@link ISourceViewer#configure(SourceViewerConfiguration)}.
 	 */
 	void unconfigure();
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IVerticalRuler.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IVerticalRuler.java
index afb7615ae37..97e6ce409fa 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IVerticalRuler.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IVerticalRuler.java
@@ -8,7 +8,6 @@
  * Contributors:
  *     IBM Corporation - initial API and implementation
  *******************************************************************************/
-
 package org.eclipse.jface.text.source;
 
 
@@ -19,26 +18,39 @@ import org.eclipse.jface.text.ITextViewer;
 
 
 /**
- * This interface defines a visual component which may serve text viewers as an annotation presentation 
- * area. Implementers of this interface have to define the presentation modus. This can either depend
- * on the connected viewer's view port or not. If the modus is view port dependent the ruler only shows 
- * those annotations that are attached to document regions that are visible in the view port. If independent,
- * the presented annotations can also be attached to invisible document regions.
+ * This interface defines a visual component which may serve text viewers as an
+ * annotation presentation area. Implementers of this interface have to define
+ * the presentation modus. This can either depend on the connected viewer's view
+ * port or not. If the modus is view port dependent the ruler only shows those
+ * annotations that are attached to document regions that are visible in the
+ * view port. If independent, the presented annotations can also be attached to
+ * invisible document regions.
  * 
  * This interfaces comprises three contracts:
  * <ul>
- * <li> The vertical ruler retrieves the annotations it presents from an annotation model.
- * <li> The ruler is a visual component which must be integrated in a hierarchy of SWT controls.
- * <li> The ruler provides interested clients with mapping and
- * 		interaction information. This covers the mapping between
- * 		coordinates of the ruler's control and line numbers based 
- * 		on the connected text viewer's document (<code>IVerticalRulerInfo</code>).
+ * <li>The vertical ruler retrieves the annotations it presents from an
+ *     annotation model.
+ * <li>The ruler is a visual component which must be integrated in a hierarchy
+ *     of SWT controls.
+ * <li>The ruler provides interested clients with mapping and interaction
+ *     information. This covers the mapping between coordinates of the ruler's
+ *     control and line numbers based on the connected text viewer's document (see
+ *     {@link org.eclipse.jface.text.source.IVerticalRulerInfo}).
+ * </ul>
+ * <p>
+ * In order to provide backward compatibility for clients of
+ * <code>IVerticalRuler</code>, extension interfaces are used as a means of
+ * evolution. The following extension interfaces exist:
+ * <ul>
+ * <li>{@link org.eclipse.jface.text.source.IVerticalRulerExtension} since
+ *     version 2.0 introducing setters for font and mouse button activity location.</li>
  * </ul>
- * Clients may implement this interface or use the default implementation provided
- * by <code>CompositeRuler</code> and <code>VerticalRuler</code>.
- *  
- * @see ITextViewer
- * @see IVerticalRulerInfo
+ * Clients may implement this interface or use the default implementation
+ * provided by {@link org.eclipse.jface.text.source.CompositeRuler} and
+ * {@link org.eclipse.jface.text.source.VerticalRuler}.
+ * 
+ * @see org.eclipse.jface.text.source.IVerticalRulerExtension
+ * @see org.eclipse.jface.text.ITextViewer
  */
 public interface IVerticalRuler extends IVerticalRulerInfo {
 
@@ -60,7 +72,7 @@ public interface IVerticalRuler extends IVerticalRulerInfo {
 		
 	/**
 	 * Forces the vertical ruler to synchronize itself with its 
-	 * annotation model and its viewer's viewport.
+	 * annotation model and its viewer's view port.
 	 */
 	void update();
 	
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IVerticalRulerColumn.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IVerticalRulerColumn.java
index 1beb941445e..de326ca8d4c 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IVerticalRulerColumn.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IVerticalRulerColumn.java
@@ -8,7 +8,6 @@
  * Contributors:
  *     IBM Corporation - initial API and implementation
  *******************************************************************************/
-
 package org.eclipse.jface.text.source;
 
 
@@ -18,11 +17,12 @@ import org.eclipse.swt.widgets.Control;
 
 
 /**
- * A <code>IVerticalRulerColumn</code> is an element that can be added
- * to a composite vertical ruler. A composite vertical ruler is a vertical ruler
- * with a dynamically changing appearance and behavior depending on its
- * actual arrangement of ruler columns. A vertical ruler column supports a
- * subset of the contract of a  vertical ruler.
+ * A vertical ruler column is an element that can be added to a composite
+ * vertical ruler ({@link org.eclipse.jface.text.source.CompositeRuler}). A
+ * composite vertical ruler is a vertical ruler with  dynamically changing
+ * appearance and behavior depending on its actual arrangement of ruler columns.
+ * A vertical ruler column supports a subset of the contract of a vertical
+ * ruler.
  * 
  * @see org.eclipse.jface.text.source.CompositeRuler
  * @since 2.0
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IVerticalRulerExtension.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IVerticalRulerExtension.java
index 5eb8a1eeed0..c53672aa7f4 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IVerticalRulerExtension.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IVerticalRulerExtension.java
@@ -8,7 +8,6 @@
  * Contributors:
  *     IBM Corporation - initial API and implementation
  *******************************************************************************/
-
 package org.eclipse.jface.text.source;
 
  
@@ -16,8 +15,10 @@ import org.eclipse.swt.graphics.Font;
 
 
 /**
- * Extension interface for <code>IVerticalRuler</code>. Allows to set the font of the
- * vertical ruler and to set the location of the last mouse button activity.
+ * Extension interface for {@link IVerticalRuler}.
+ * <p>
+ * Allows to set the font of the vertical ruler and to set the location of the
+ * last mouse button activity.
  * 
  * @since 2.0
  */
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IVerticalRulerInfo.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IVerticalRulerInfo.java
index 26120a1ca26..b6dadc6f68c 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IVerticalRulerInfo.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IVerticalRulerInfo.java
@@ -16,14 +16,22 @@ import org.eclipse.swt.widgets.Control;
 
 
 /**
- * A vertical ruler is a visual component which may serve
- * text viewers as an annotation presentation 
- * area. The vertical ruler info provides interested clients with the
- * mapping and interaction aspect of the vertical ruler. This
- * covers the mapping between coordinates of the ruler's
- * control and line numbers based on the connected text viewer's
- * document.
+ * A vertical ruler is a visual component which may serve text viewers as an
+ * annotation presentation area. The vertical ruler info provides interested
+ * clients with the mapping and interaction aspect of the vertical ruler. This
+ * covers the mapping between coordinates of the ruler's control and line
+ * numbers based on the connected text viewer's document.
  * 
+ * In order to provide backward compatibility for clients of
+ * <code>IVerticalRulerInfo</code>, extension interfaces are used as a means
+ * of evolution. The following extension interfaces exist:
+ * <ul>
+ * <li>{@link org.eclipse.jface.text.source.IVerticalRulerInfoExtension} since
+ * version 3.0 allowing custom annotation hovers and specific annotation models.
+ * </li>
+ * </ul>
+ * 
+ * @see org.eclipse.jface.text.source.IVerticalRulerInfoExtension
  * @since 2.0
  */
 public interface IVerticalRulerInfo {
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IVerticalRulerInfoExtension.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IVerticalRulerInfoExtension.java
index d9369481460..458e7892c17 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IVerticalRulerInfoExtension.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IVerticalRulerInfoExtension.java
@@ -11,21 +11,34 @@
 package org.eclipse.jface.text.source;
 
 /**
- * Extends <code>IVerticalRulerInfo</code> with the ability to define a custom hover to be used
- * when hovering over the <code>IVerticalRuler</code> described by this info instance, and to
- * specify the <code>IAnnotationModel</code> used by it.
+ * Extension interface for
+ * {@link org.eclipse.jface.text.source.IVerticalRulerInfo}.
+ * <p>
+ * Introduces the ability to define a custom hover to be used when hovering over
+ * the vertical ruler described by this info instance, and to specify the
+ * annotation model used by it.
+ * <p>
+ * It also allows client to register as listeners on the represented vertical
+ * ruler and sends out notifications similar to selection events such as that a
+ * particular annotation presented in the vertical ruler has been selected.
+ * 
+ * @see org.eclipse.jface.text.source.IVerticalRuler
+ * @see org.eclipse.jface.text.source.IAnnotationModel
  * @since 3.0
  */
 public interface IVerticalRulerInfoExtension {
 	/**
 	 * Returns the hover for this vertical ruler (column).
+	 * 
 	 * @return the hover for this column
 	 */
 	IAnnotationHover getHover();
 	
 	/**
 	 * Returns the model currently used by the receiver.
-	 * @return the model of the receiver, or <code>null</code> if no model is installed.
+	 * 
+	 * @return the model of the receiver, or <code>null</code> if no model is
+	 *         installed.
 	 */
 	IAnnotationModel getModel();
 	
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IVerticalRulerListener.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IVerticalRulerListener.java
index 1ee9aca0e9b..390abb594b0 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IVerticalRulerListener.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/IVerticalRulerListener.java
@@ -24,7 +24,7 @@ import org.eclipse.swt.widgets.Menu;
 public interface IVerticalRulerListener {
 	
 	/**
-	 * Called when an annotation is selected in the UI.
+	 * Called when an annotation is selected in the vertical ruler.
 	 * 
 	 * @param event the annotation event that occurred
 	 */
@@ -32,14 +32,15 @@ public interface IVerticalRulerListener {
 	
 	/**
 	 * Called when a default selection occurs on an 
-	 * annotation.
+	 * annotation in the vertical ruler.
 	 * 
 	 * @param event the annotation event that occurred
 	 */
 	void annotationDefaultSelected(VerticalRulerEvent event);
 	
 	/** 
-	 * Called when the context menu is opened on an annotation.
+	 * Called when the context menu is opened on an annotation in the 
+	 * vertical ruler.
 	 * 
 	 * @param event the annotation event that occurred
 	 * @param menu the menu that is about to be shown
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/LineRange.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/LineRange.java
index ca6f447faae..e7cf3822473 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/LineRange.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/LineRange.java
@@ -11,6 +11,8 @@
 package org.eclipse.jface.text.source;
 
 /**
+ * Default implements of {@link LineRange}.<p>
+ * 
  * @since 3.0
  */
 public final class LineRange implements ILineRange {
@@ -18,6 +20,12 @@ public final class LineRange implements ILineRange {
 	private int fStartLine;
 	private int fNumberOfLines;
 	
+	/**
+	 * Creates a new line range with the given specification.
+	 * 
+	 * @param startLine the start line
+	 * @param numberOfLines the number of lines
+	 */
 	public LineRange(int startLine, int numberOfLines) {
 		fStartLine= startLine;
 		fNumberOfLines= numberOfLines;
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/MatchingCharacterPainter.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/MatchingCharacterPainter.java
index e0329051d1b..4f88ecc3fdb 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/MatchingCharacterPainter.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/MatchingCharacterPainter.java
@@ -28,8 +28,10 @@ import org.eclipse.jface.text.Position;
 import org.eclipse.jface.text.Region;
 
 /**
- * Highlights the peer character matching the character near the caret position. This
- * painter can be configured with an <code>ICharacterPairMatcher</code>.
+ * Highlights the peer character matching the character near the caret position.
+ * This painter can be configured with an
+ * {@link org.eclipse.jface.text.source.ICharacterPairMatcher}.
+ * <p>
  * Clients instantiate and configure object of this class.
  * 
  * @since 2.1
@@ -46,7 +48,7 @@ public final class MatchingCharacterPainter implements IPainter, PaintListener {
 	private Color fColor;
 	/** The paint position manager */
 	private IPaintPositionManager fPaintPositionManager;
-	/** The startegy for finding matching characters */
+	/** The strategy for finding matching characters */
 	private ICharacterPairMatcher fMatcher;
 	/** The position tracking the matching characters */
 	private Position fPairPosition= new Position(0, 0);
@@ -58,7 +60,7 @@ public final class MatchingCharacterPainter implements IPainter, PaintListener {
 	 * Creates a new MatchingCharacterPainter for the given source viewer using
 	 * the given character pair matcher. The character matcher is not adopted by
 	 * this painter. Thus,  it is not disposed. However, this painter requires
-	 * exlucsive access to the given pair matcher.
+	 * exclusive access to the given pair matcher.
 	 * 
 	 * @param sourceViewer
 	 * @param matcher
@@ -116,7 +118,7 @@ public final class MatchingCharacterPainter implements IPainter, PaintListener {
 	/**
 	 * Handles a redraw request.
 	 * 
-	 * @param gc the gc to draw into.
+	 * @param gc the GC to draw into.
 	 */
 	private void handleDrawRequest(GC gc) {
 		
@@ -165,7 +167,7 @@ public final class MatchingCharacterPainter implements IPainter, PaintListener {
 	/**
 	 * Highlights the given widget region.
 	 * 
-	 * @param gc the gc to draw into
+	 * @param gc the GC to draw into
 	 * @param offset the offset of the widget region
 	 * @param length the length of the widget region
 	 */
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/OverviewRuler.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/OverviewRuler.java
index aa5e95e2b3b..420a57a2f0a 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/OverviewRuler.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/OverviewRuler.java
@@ -8,9 +8,9 @@
  * Contributors:
  *     IBM Corporation - initial API and implementation
  *******************************************************************************/
-
 package org.eclipse.jface.text.source;
 
+
 import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.HashSet;
@@ -102,7 +102,12 @@ public class OverviewRuler implements IOverviewRuler {
 		private Annotation fNext;
 		private int fStyle;
 		
-				
+		/**
+		 * Creates a new filter iterator with the given specification.
+		 * 
+		 * @param annotationType the annotation type
+		 * @param style the style
+		 */
 		public FilterIterator(Object annotationType, int style) {
 			fType= annotationType;
 			fStyle= style;
@@ -112,6 +117,13 @@ public class OverviewRuler implements IOverviewRuler {
 			}
 		}
 		
+		/**
+		 * Creates a new filter iterator with the given specification.
+		 * 
+		 * @param annotationType the annotation type
+		 * @param style the style
+		 * @param iterator the iterator
+		 */
 		public FilterIterator(Object annotationType, int style, Iterator iterator) {
 			fType= annotationType;
 			fStyle= style;
@@ -186,10 +198,18 @@ public class OverviewRuler implements IOverviewRuler {
 		private Color fIndicatorColor;
 		private Color fSeparatorColor;
 		
+		/**
+		 * Creates a new header painter.
+		 */
 		public HeaderPainter() {
 			fSeparatorColor= fSharedTextColors.getColor(ViewForm.borderInsideRGB);
 		}
 		
+		/**
+		 * Sets the header color.
+		 * 
+		 * @param color the header color
+		 */
 		public void setColor(Color color) {
 			fIndicatorColor= color;
 		}
@@ -237,7 +257,7 @@ public class OverviewRuler implements IOverviewRuler {
 	private Canvas fCanvas;
 	/** The ruler's header */
 	private Canvas fHeader;
-	/** The drawable for double buffering */
+	/** The buffer for double buffering */
 	private Image fBuffer;
 	/** The internal listener */
 	private InternalListener fInternalListener= new InternalListener();
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/OverviewRulerHoverManager.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/OverviewRulerHoverManager.java
index 765d3ebdf21..d65f284fcac 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/OverviewRulerHoverManager.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/OverviewRulerHoverManager.java
@@ -57,7 +57,7 @@ class OverviewRulerHoverManager extends AnnotationBarHoverManager {
 	 * @return the graphical extend where the hover is valid
 	 */
 	private Rectangle computeArea(int y) {
-		// This is ok (see constructor)
+		// This is OK (see constructor)
 		IOverviewRuler overviewRuler= (IOverviewRuler) getVerticalRulerInfo();
 
 		int hover_height= overviewRuler.getAnnotationHeight();
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/SourceViewer.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/SourceViewer.java
index 7ad0d4f807e..fae7c4b2bce 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/SourceViewer.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/SourceViewer.java
@@ -8,7 +8,6 @@
  * Contributors:
  *     IBM Corporation - initial API and implementation
  *******************************************************************************/
-
 package org.eclipse.jface.text.source;
 
 import java.util.Stack;
@@ -47,15 +46,22 @@ import org.eclipse.jface.text.projection.ChildDocument;
 import org.eclipse.jface.text.reconciler.IReconciler;
 
 /**
- * SWT based implementation of <code>ISourceViewer</code>. The same rules apply 
- * as for <code>TextViewer</code>. A source viewer uses an <code>IVerticalRuler</code>
- * as its annotation presentation area. The vertical ruler is a small strip shown left
- * of the viewer's text widget. A source viewer uses an <code>IOverviewRuler</code>
- * as its presentation area for the annotation overview. The overview ruler is a small strip
- * shown right of the viewer's text widget.<p>
- * Clients are supposed to instantiate a source viewer and subsequently to communicate
- * with it exclusively using the <code>ISourceViewer</code> interface. Clients should not
- * subclass this class as it is rather likely that subclasses will be broken by future releases. 
+ * SWT based implementation of
+ * {@link org.eclipse.jface.text.source.ISourceViewer}and its extension
+ * interfaces. The same rules apply as for
+ * {@link org.eclipse.jface.text.TextViewer}. A source viewer uses an
+ * <code>IVerticalRuler</code> as its annotation presentation area. The
+ * vertical ruler is a small strip shown left of the viewer's text widget. A
+ * source viewer uses an <code>IOverviewRuler</code> as its presentation area
+ * for the annotation overview. The overview ruler is a small strip shown right
+ * of the viewer's text widget.
+ * <p>
+ * Clients are supposed to instantiate a source viewer and subsequently to
+ * communicate with it exclusively using the <code>ISourceViewer</code>
+ * interface.
+ * <p>
+ * Clients should not subclass this class as it is rather likely that subclasses
+ * will be broken by future releases.
  */
 public class SourceViewer extends TextViewer implements ISourceViewer, ISourceViewerExtension, ISourceViewerExtension2 {
 
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/SourceViewerConfiguration.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/SourceViewerConfiguration.java
index cf803ad251a..f9cc9b4fa89 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/SourceViewerConfiguration.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/SourceViewerConfiguration.java
@@ -8,7 +8,6 @@
  * Contributors:
  *     IBM Corporation - initial API and implementation
  *******************************************************************************/
-
 package org.eclipse.jface.text.source;
 
 
@@ -35,17 +34,20 @@ import org.eclipse.jface.text.reconciler.IReconciler;
 
 
 /**
- * This class bundles the whole configuration space of a source viewer.
- * Instances of this class are passed to the <code>configure</code> method of
- * <code>ISourceViewer</code>.<p>
- * Each method in this class get as argument the source viewer for which it should
- * provide a particular configurational setting such as a presentation reconciler.
- * Based on its specific knowledge about the returned object, the configuration 
- * might share such objects or compute them according to some rules.<p>
- * Clients should subclass and override just those methods which must be specific to
- * their needs.
- *
- * @see ISourceViewer
+ * This class bundles the configuration space of a source viewer. Instances of
+ * this class are passed to the <code>configure</code> method of
+ * <code>ISourceViewer</code>.
+ * <p>
+ * Each method in this class get as argument the source viewer for which it
+ * should provide a particular configuration setting such as a presentation
+ * reconciler. Based on its specific knowledge about the returned object, the
+ * configuration might share such objects or compute them according to some
+ * rules.
+ * <p>
+ * Clients should subclass and override just those methods which must be
+ * specific to their needs.
+ * 
+ * @see org.eclipse.jface.text.source.ISourceViewer
  */
 public class SourceViewerConfiguration {
 	
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/VerticalRuler.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/VerticalRuler.java
index 4f91520a741..76f95cf62d3 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/VerticalRuler.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/VerticalRuler.java
@@ -11,8 +11,6 @@
 package org.eclipse.jface.text.source;
 
 
-
-
 import java.util.Iterator;
 
 import org.eclipse.swt.SWT;
@@ -46,12 +44,14 @@ import org.eclipse.jface.text.TextEvent;
 
 
 /**
- * A vertical ruler which is connected to a text viewer. Single column standard 
- * implementation of <code>IVerticalRuler</code>. The same can be achieved by 
- * using <code>CompositeRuler</code> configured with an <code>AnnotationRulerColumn</code>.
- * Clients may use this class as is.
- *
- * @see ITextViewer
+ * A vertical ruler which is connected to a text viewer. Single column standard
+ * implementation of {@link org.eclipse.jface.text.source.IVerticalRuler}.
+ * <p>
+ * The same can be achieved by using <code>CompositeRuler</code> configured
+ * with an <code>AnnotationRulerColumn</code>. Clients may use this class as
+ * is.
+ * 
+ * @see org.eclipse.jface.text.ITextViewer
  */
 public final class VerticalRuler implements IVerticalRuler, IVerticalRulerExtension {
 
@@ -92,7 +92,7 @@ public final class VerticalRuler implements IVerticalRuler, IVerticalRulerExtens
 	private IAnnotationModel fModel;
 	/** Cache for the actual scroll position in pixels */
 	private int fScrollPos;
-	/** The drawable for double buffering */
+	/** The buffer for double buffering */
 	private Image fBuffer;
 	/** The line of the last mouse button activity */
 	private int fLastMouseButtonActivityLine= -1;
@@ -242,7 +242,7 @@ public final class VerticalRuler implements IVerticalRuler, IVerticalRulerExtens
 	
 	/**
 	 * Returns the document offset of the upper left corner of the
-	 * widgets viewport, possibly including partially visible lines.
+	 * widgets view port, possibly including partially visible lines.
 	 * 
 	 * @return the document offset of the upper left corner including partially visible lines
 	 * @since 2.0
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/VisualAnnotationModel.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/VisualAnnotationModel.java
index 7c160f2b3e9..01c20c191d6 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/VisualAnnotationModel.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/VisualAnnotationModel.java
@@ -11,8 +11,6 @@
 package org.eclipse.jface.text.source;
 
 
-
-
 import java.util.ArrayList;
 import java.util.Iterator;
 
@@ -23,7 +21,7 @@ import org.eclipse.jface.text.Position;
 
 /**
  * Annotation model for visual annotations. Assume a viewer's input element is annotated with
- * some semantic annotation such as a breakpoint and that it is simultanously shown in multiple
+ * some semantic annotation such as a breakpoint and that it is simultaneously shown in multiple
  * viewers. A source viewer, e.g., supports visual range indication for which it utilizes
  * annotations. The range indicating annotation is specific to the visual presentation
  * of the input element in this viewer and thus should only be visible in this viewer. The