JavaDoc

12 files changed, 273 insertions, 69 deletions

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 7f936d8d850..8715073c02d 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
@@ -17,7 +17,8 @@ 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
- * the text viewer. The ruler shows annotations of the viewer's whole document
+ * the text viewer. The annotations of the viewer's whole document are 
+ * visible in the overview ruler.
  * 
  * This interfaces comprises three contracts:
  * <ul>
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 01d19664cec..008399a0e4c 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,14 +12,26 @@
 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 viewport, 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>.
+ * 
  * @since 2.1
  */
 public interface ISourceViewerExtension {
 	
 	/**
-	 * Shows/hides an overview representation of all annotations.
+	 * Shows/hides an overview representation of the annotations of the whole document of this viewer.
 	 * 
-	 * @param show the flag that indicates whether the 
+	 * @param show <code>true</code> if annotation overview should be visible, <code>false</code> otherwise
 	 */
 	void showAnnotationsOverview(boolean show);
 }
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 e6fd57ef015..5e7c9b91370 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
@@ -19,19 +19,23 @@ import org.eclipse.jface.text.ITextViewer;
 
 
 /**
- * This interface defines a visual component which may serve
- * text viewers as a line oriented annotation presentation 
- * area. This interfaces comprises three contracts:
+ * 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 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>).
  * </ul>
  * Clients may implement this interface or use the default implementation provided
- * by <code>VerticalRuler</code>.
+ * by <code>CompositeRuler</code> and <code>VerticalRuler</code>.
  *  
  * @see ITextViewer
  * @see IVerticalRulerInfo
@@ -40,9 +44,6 @@ public interface IVerticalRuler extends IVerticalRulerInfo {
 
 	/**
 	 * Associates an annotation model with this ruler.
-	 * If the ruler is visible it must display those annotions
-	 * of the annotation model whose visual representation overlaps
-	 * with the viewport of the rulers source viewer.
 	 * A value <code>null</code> is acceptable and clears the ruler.
 	 *
 	 * @param model the new annotation model, may be <code>null</code>
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 59209a91783..2c442e6933f 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
@@ -22,7 +22,7 @@ import org.eclipse.swt.widgets.Control;
  * 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 full vertical ruler.
+ * 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 0a57e7d9e21..14f55d639b6 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
@@ -16,7 +16,9 @@ import org.eclipse.swt.graphics.Font;
 
 
 /**
- * Extension interface for <code>IVerticalRuler</code>.
+ * 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.
+ * 
  * @since 2.0
  */
 public interface IVerticalRulerExtension {
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 9dc03fa1534..0b686eb2d5d 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
@@ -17,12 +17,13 @@ import org.eclipse.swt.widgets.Control;
 
 /**
  * A vertical ruler is a visual component which may serve
- * text viewers as a line oriented annotation presentation 
- * area. The ruler info provides interested clients with the
+ * 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.
+ * 
  * @since 2.0
  */
 public interface IVerticalRulerInfo {
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/LineNumberRulerColumn.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/LineNumberRulerColumn.java
index afb66570c0d..b6c82d081ab 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/LineNumberRulerColumn.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/LineNumberRulerColumn.java
@@ -46,7 +46,8 @@ import org.eclipse.jface.text.TextEvent;
 
 /**
  * A vertical ruler column displaying line numbers.
- * Clients may use this class as is.
+ * Clients usually instantiate and configure object of this class.
+ * 
  * @since 2.0
  */
 public final class LineNumberRulerColumn implements IVerticalRulerColumn {
@@ -98,9 +99,13 @@ public final class LineNumberRulerColumn implements IVerticalRulerColumn {
 	 */
 	class MouseHandler implements MouseListener, MouseMoveListener, MouseTrackListener {
 		
+		/** The cached view port size */
 		private int fCachedViewportSize;
+		/** The area of the line at which line selection started */
 		private IRegion fStartLine;
+		/** The number of the line at which line selection started */
 		private int fStartLineNumber;
+		/** The auto scroll direction */
 		private int fAutoScrollDirection;
 	
 		/*
@@ -156,6 +161,10 @@ public final class LineNumberRulerColumn implements IVerticalRulerColumn {
 		public void mouseHover(MouseEvent event) {
 		}
 				
+		/**
+		 * Called when line drag selection started. Adds mouse move and track
+		 * listeners to this column's control.
+		 */
 		private void startSelecting() {
 			try {
 				
@@ -174,12 +183,22 @@ public final class LineNumberRulerColumn implements IVerticalRulerColumn {
 			}
 		}
 		
+		/**
+		 * Called when line drag selection stopped. Removes all previously
+		 * installed listeners from this column's control.
+		 */
 		private void stopSelecting() {
 			// drag selection stopped
 			fCanvas.removeMouseMoveListener(this);
 			fCanvas.removeMouseTrackListener(this);
 		}
 		
+		/**
+		 * Expands the line selection from the remembered start line to the
+		 * given line.
+		 * 
+		 * @param lineNumber the line to which to expand the selection
+		 */
 		private void expandSelection(int lineNumber) {
 			try {
 				
@@ -198,15 +217,18 @@ public final class LineNumberRulerColumn implements IVerticalRulerColumn {
 			}
 		}
 		
-		/*
-		 * Follows the scheme of StyledText. 
+		/**
+		 * Called when auto scrolling stopped. Clears the auto scroll direction.
 		 */
 		private void stopAutoScroll() {
 			fAutoScrollDirection= SWT.NULL;
 		}		
 		
-		/*
-		 * Follows the scheme of StyledText. 
+		/**
+		 * Called on drag selection.
+		 * 
+		 * @param event the mouse event caught by the mouse move listener
+		 * @return <code>true</code> if scrolling happend, <code>false</code> otherwise
 		 */
 		private boolean autoScroll(MouseEvent event) {
 			Rectangle area= fCanvas.getClientArea();
@@ -225,8 +247,10 @@ public final class LineNumberRulerColumn implements IVerticalRulerColumn {
 			return false;
 		}
 		
-		/*
-		 * Follows the scheme of StyledText. 
+		/**
+		 * Scrolls the viewer into the given direction.
+		 * 
+		 * @param direction the scroll direction
 		 */
 		private void autoScroll(int direction) {
 						
@@ -271,6 +295,11 @@ public final class LineNumberRulerColumn implements IVerticalRulerColumn {
 			}
 		}
 		
+		/**
+		 * Returns the viewer's first visible line, even if only partially visible.
+		 * 
+		 * @return the viewer's first visible line
+		 */
 		private int getInclusiveTopIndex() {
 			if (fCachedTextWidget != null && !fCachedTextWidget.isDisposed()) {	
 				int top= fCachedTextViewer.getTopIndex();
@@ -393,6 +422,8 @@ public final class LineNumberRulerColumn implements IVerticalRulerColumn {
 	/**
 	 * Layouts the enclosing viewer to adapt the layout to changes of the
 	 * size of the individual components.
+	 * 
+	 * @param redraw <code>true</code> if this column can be redrawn
 	 */
 	protected void layout(boolean redraw) {
 		if (!redraw) {
@@ -609,6 +640,12 @@ public final class LineNumberRulerColumn implements IVerticalRulerColumn {
 		}
 	}
 	
+	/**
+	 * Draws the ruler column. Uses <code>ITextViewerExtension3</code> for the
+	 * implementation. Will replace <code>doPinat(GC)</code>.
+	 * 
+	 * @param gc the gc to draw into
+	 */
 	private void doPaint1(GC gc) {
 
 		if (fCachedTextViewer == null)
@@ -669,7 +706,7 @@ public final class LineNumberRulerColumn implements IVerticalRulerColumn {
 	}
 	
 	/*
-	 * @see IVerticalRulerColumn#redraw
+	 * @see IVerticalRulerColumn#redraw()
 	 */
 	public void redraw() {
 		
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 d3b2bea7ed5..0520a7b950d 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
@@ -27,26 +27,36 @@ import org.eclipse.jface.text.Position;
 import org.eclipse.jface.text.Region;
 
 /**
- * Highlights the peer character matching the character at the current
- * selection.
+ * Highlights the peer character matching the character near the caret position. This
+ * painter can be configured with an <code>ICharacterPairMatcher</code>.
+ * Clients instantiate and configure object of this class.
+ * 
+ * @since 2.1
  */
 public final class MatchingCharacterPainter implements IPainter, PaintListener {
-			
+	
+	/** Indicates whether this painter is active */
 	private boolean fIsActive= false;
+	/** The source viewer this painter is associated with */
 	private ISourceViewer fSourceViewer;
+	/** The viewer's widget */
 	private StyledText fTextWidget;
+	/** The color in which to highlight the peer character */
 	private Color fColor;
-	
+	/** The paint position manager */
 	private IPaintPositionManager fPaintPositionManager;
+	/** The startegy for finding matching characters */
 	private ICharacterPairMatcher fMatcher;
+	/** The position tracking the matching characters */
 	private Position fPairPosition= new Position(0, 0);
+	/** The anchor indicating whether the character is left or right of the caret */
 	private int fAnchor;
 
 	
 	/**
 	 * 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 painters requires
+	 * this painter. Thus,  it is not disposed. However, this painter requires
 	 * exlucsive access to the given pair matcher.
 	 * 
 	 * @param sourceViewer
@@ -58,6 +68,11 @@ public final class MatchingCharacterPainter implements IPainter, PaintListener {
 		fTextWidget= sourceViewer.getTextWidget();
 	}
 	
+	/**
+	 * Sets the color in which to highlight the match character.
+	 * 
+	 * @param color the color
+	 */
 	public void setColor(Color color) {
 		fColor= color;
 	}
@@ -97,6 +112,11 @@ public final class MatchingCharacterPainter implements IPainter, PaintListener {
 			handleDrawRequest(event.gc);
 	}
 	
+	/**
+	 * Handles a redraw request.
+	 * 
+	 * @param gc the gc to draw into.
+	 */
 	private void handleDrawRequest(GC gc) {
 		
 		if (fPairPosition.isDeleted)
@@ -129,6 +149,13 @@ public final class MatchingCharacterPainter implements IPainter, PaintListener {
 			draw(gc, offset + length -1, 1);
 	}
 	
+	/**
+	 * Highlights the given widget region.
+	 * 
+	 * @param gc the gc to draw into
+	 * @param offset the offset of the widget region
+	 * @param length the length of the widget region
+	 */
 	private void draw(GC gc, int offset, int length) {
 		if (gc != null) {
 			Point left= fTextWidget.getLocationAtOffset(offset);
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 5f511a0577b..531f8fa1f40 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
@@ -57,7 +57,10 @@ import org.eclipse.jface.text.TextEvent;
 /**
  * Ruler presented next to a source viewer showing all annotations of the
  * viewer's annotation model in a compact format, i.e. using the same height as
- * the source viewer.
+ * the source viewer.<p>
+ * Clients usually instantiate and configure objects of this class.
+ * 
+ * @since 2.1
  */
 public class OverviewRuler implements IOverviewRuler {
 	
@@ -85,7 +88,8 @@ public class OverviewRuler implements IOverviewRuler {
 	};
 	
 	/**
-	 * Filters annotations based on their types.
+	 * Enumerates the annotations of a specified type and characteristics
+	 * of the associated annotation model.
 	 */
 	class FilterIterator implements Iterator {
 		
@@ -162,6 +166,9 @@ public class OverviewRuler implements IOverviewRuler {
 		}
 	};
 	
+	/**
+	 * The painter of the overview ruler's header.
+	 */
 	class HeaderPainter implements PaintListener {
 		
 		private Color fIndicatorColor;
@@ -237,19 +244,26 @@ public class OverviewRuler implements IOverviewRuler {
 	private IAnnotationAccess fAnnotationAccess;
 	/** The header painter */
 	private HeaderPainter fHeaderPainter;
-	
+	/** The list of annotation types to be shown in this ruler */
 	private Set fAnnotationTypes= new HashSet();
+	/** The list of annotation types to be shown in the header of this ruler */
 	private Set fHeaderAnnotationTypes= new HashSet();
+	/** The mapping between annotation types and drawing layers */
 	private Map fAnnotationTypes2Layers= new HashMap();
+	/** The mapping between annotation types and colors */
 	private Map fAnnotationTypes2Colors= new HashMap();
+	/** The color manager */
 	private ISharedTextColors fSharedTextColors;
 	
 	
 	
 	/**
-	 * Constructs a vertical ruler with the given width.
+	 * Constructs a overview ruler of the given width using the given annotation access and the given
+	 * color manager.
 	 *
+	 * @param annotationAccess the annotation access
 	 * @param width the width of the vertical ruler
+	 * @param sharedColors the color manager
 	 */
 	public OverviewRuler(IAnnotationAccess annotationAccess, int width, ISharedTextColors sharedColors) {
 		fAnnotationAccess= annotationAccess;
@@ -363,6 +377,8 @@ public class OverviewRuler implements IOverviewRuler {
 
 	/**
 	 * Double buffer drawing.
+	 * 
+	 * @param dest the gc to draw into
 	 */
 	private void doubleBufferPaint(GC dest) {
 		
@@ -398,6 +414,11 @@ public class OverviewRuler implements IOverviewRuler {
 		dest.drawImage(fBuffer, 0, 0);
 	}
 	
+	/** 
+	 * Draws this overview ruler.
+	 * 
+	 * @param gc the gc to draw into
+	 */
 	private void doPaint(GC gc) {
 		
 		if (fTextViewer == null)
@@ -482,6 +503,12 @@ public class OverviewRuler implements IOverviewRuler {
 		}
 	}
 	
+	/**
+	 * Draws this overview ruler. Uses <code>ITextViewerExtension3</code> for
+	 * its implementation. Will replace <code>doPaint(GC)</code>.
+	 * 
+	 * @param gc the gc to draw into
+	 */
 	private void doPaint1(GC gc) {
 
 		if (fTextViewer == null)
@@ -591,6 +618,15 @@ public class OverviewRuler implements IOverviewRuler {
 		}
 	}
 	
+	/**
+	 * Translates a given y-coordinate of this ruler into the corresponding
+	 * document lines. The number of lines depends on the concrete scaling
+	 * given as the ration between the height of this ruler and the length
+	 * of the document.
+	 * 
+	 * @param y_coordinate the y-coordinate
+	 * @return the corresponding document lines
+	 */
 	private int[] toLineNumbers(int y_coordinate) {
 					
 		StyledText textWidget=  fTextViewer.getTextWidget();
@@ -630,6 +666,12 @@ public class OverviewRuler implements IOverviewRuler {
 		return lines;
 	}
 	
+	/**
+	 * Returns the position of the first annotation found in the given line range.
+	 * 
+	 * @param lineNumbers the line range
+	 * @return the position of the first found annotation
+	 */
 	private Position getAnnotationPosition(int[] lineNumbers) {
 		if (lineNumbers[0] == -1)
 			return null;
@@ -662,11 +704,10 @@ public class OverviewRuler implements IOverviewRuler {
 	}
 
 	/**
-	 * Returns the line which best corresponds to one of
-	 * the underlying annotations at the given y ruler coordinate.
+	 * Returns the line which  corresponds best to one of
+	 * the underlying annotations at the given y-coordinate.
 	 * 
-	 * @return the best matching line or <code>-1</code> if no such line can be
-	 * found
+	 * @return the best matching line or <code>-1</code> if no such line can be found
 	 */
 	private int findBestMatchingLineNumber(int[] lineNumbers) {
 		if (lineNumbers == null || lineNumbers.length < 1)
@@ -682,6 +723,11 @@ public class OverviewRuler implements IOverviewRuler {
 		}
 	}
 
+	/**
+	 * Handles mouse clicks.
+	 * 
+	 * @param event the mouse button down event
+	 */
 	private void handleMouseDown(MouseEvent event) {
 		if (fTextViewer != null) {
 			int[] lines= toLineNumbers(event.y);
@@ -695,6 +741,11 @@ public class OverviewRuler implements IOverviewRuler {
 		fLastMouseButtonActivityLine= toDocumentLineNumber(event.y);
 	}
 	
+	/**
+	 * Handles mouse moves.
+	 * 
+	 * @param event the mouse move event
+	 */
 	private void handleMouseMove(MouseEvent event) {
 		if (fTextViewer != null) {
 			int[] lines= toLineNumbers(event.y);
@@ -721,12 +772,8 @@ public class OverviewRuler implements IOverviewRuler {
 		fAnnotationTypes.remove(annotationType);
 	}
 		
-	/**
-	 * Sets the layer at which annotations of the given annotation type are
-	 * drawn. Layers are drawn in ascending order.
-	 * 
-	 * @param annotationType
-	 * @param layer
+	/*
+	 * @see org.eclipse.jface.text.source.IOverviewRuler#setAnnotationTypeLayer(java.lang.Object, int)
 	 */
 	public void setAnnotationTypeLayer(Object annotationType, int layer) {
 		if (layer >= 0)
@@ -753,10 +800,25 @@ public class OverviewRuler implements IOverviewRuler {
 			fAnnotationTypes2Colors.remove(annotationType);
 	}
 	
+	/**
+	 * Returns whether annotation of the given annotation type should be skipped by the drawing routine.
+	 * 
+	 * @param annotationType the annotation type
+	 * @return <code>true</code> if annotation of the given type should be skipped
+	 */
 	private boolean skip(Object annotationType) {
 		return !fAnnotationTypes.contains(annotationType);
 	}
 	
+	/**
+	 * Returns a specification of a color that lies between the given
+	 * foreground and background color using the given scale factor.
+	 * 
+	 * @param fg the foreground color
+	 * @param bg the background color
+	 * @param scale the scale factor
+	 * @return the interpolated color
+	 */
 	private static RGB interpolate(RGB fg, RGB bg, double scale) {
 		return new RGB(
 			(int) ((1.0-scale) * fg.red + scale * bg.red),
@@ -765,16 +827,35 @@ public class OverviewRuler implements IOverviewRuler {
 		);
 	}
 	
+	/**
+	 * Returns the grey value in which the given color would be drawn in grey-scale.
+	 * 
+	 * @param rgb the color
+	 * @return the grey-scale value
+	 */
 	private static double greyLevel(RGB rgb) {
 		if (rgb.red == rgb.green && rgb.green == rgb.blue)
 			return rgb.red;
 		return  (0.299 * rgb.red + 0.587 * rgb.green + 0.114 * rgb.blue + 0.5);
 	}
 	
+	/**
+	 * Returns whether the given color is dark or light depending on the colors grey-scale level.
+	 * 
+	 * @param rgb the color
+	 * @return <code>true</code> if the color is dark, <code>false</code> if it is light
+	 */
 	private static boolean isDark(RGB rgb) {
 		return greyLevel(rgb) > 128;
 	}
 	
+	/**
+	 * Returns a color based on the color configured for the given annotation type and the given scale factor.
+	 * 
+	 * @param annotationType the annotation type
+	 * @param scale the scale factor
+	 * @return the computed color
+	 */
 	private Color getColor(Object annotationType, double scale) {
 		Color base= (Color) fAnnotationTypes2Colors.get(annotationType);
 		if (base == null)
@@ -793,10 +874,24 @@ public class OverviewRuler implements IOverviewRuler {
 		return fSharedTextColors.getColor(interpolate(baseRGB, background, scale));
 	}
 	
+	/**
+	 * Returns the stroke color for the given annotation type and characteristics.
+	 * 
+	 * @param annotationType the annotation type
+	 * @param temporary <code>true</code> if for temporary annotations
+	 * @return the stroke color
+	 */
 	private Color getStrokeColor(Object annotationType, boolean temporary) {
 		return getColor(annotationType, temporary ? 0.5 : 0.2);
 	}
 	
+	/**
+	 * Returns the fill color for the given annotation type and characteristics.
+	 * 
+	 * @param annotationType the annotation type
+	 * @param temporary <code>true</code> if for temporary annotations
+	 * @return the fill color
+	 */
 	private Color getFillColor(Object annotationType, boolean temporary) {
 		return getColor(annotationType, temporary ? 0.9 : 0.6);
 	}
@@ -865,6 +960,9 @@ public class OverviewRuler implements IOverviewRuler {
 		fHeaderAnnotationTypes.remove(annotationType);
 	}
 	
+	/**
+	 * Updates the header of this ruler.
+	 */
 	private void updateHeader() {
 		
 		if (fHeader == null || fHeader.isDisposed())
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 3e57e540d3e..87f4d098cd8 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
@@ -38,7 +38,9 @@ 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.<p>
+ * 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. 
@@ -47,7 +49,7 @@ public class SourceViewer extends TextViewer implements ISourceViewer, ISourceVi
 
 
 	/**
-	 * Layout of a source viewer. Vertical ruler and text widget are shown side by side.
+	 * Layout of a source viewer. Vertical ruler, text widget, and overview ruler are shown side by side.
 	 */
 	class RulerLayout extends Layout {
 		
@@ -169,14 +171,16 @@ public class SourceViewer extends TextViewer implements ISourceViewer, ISourceVi
 	}
 	
 	/**
-	 * Constructs a new source viewer. The vertical ruler and the overview
-	 * ruler are initially visible. The viewer has not yet been initialized with
-	 * a source viewer configuration.
+	 * Constructs a new source viewer. The vertical ruler is initially visible. 
+	 * The overview ruler visibility is controlled by the value of <code>showAnnotationsOverview</code>.
+	 * The viewer has not yet been initialized with a source viewer configuration.
 	 *
 	 * @param parent the parent of the viewer's control
 	 * @param verticalRuler the vertical ruler used by this source viewer
 	 * @param overviewRuler the overview ruler
+	 * @param showAnnotationsOverview <code>true</code> if the overview ruler should be visible, <code>false</code> otherwise
 	 * @param styles the SWT style bits
+	 * @since 2.1
 	 */
 	public SourceViewer(Composite parent, IVerticalRuler verticalRuler, IOverviewRuler overviewRuler, boolean showAnnotationsOverview, int styles) {
 		super();
@@ -190,7 +194,7 @@ public class SourceViewer extends TextViewer implements ISourceViewer, ISourceVi
 	}
 	
 	/*
-	 * @see TextViewer#createControl
+	 * @see TextViewer#createControl(Composite, int)
 	 */
 	protected void createControl(Composite parent, int styles) {
 		
@@ -210,7 +214,7 @@ public class SourceViewer extends TextViewer implements ISourceViewer, ISourceVi
 	}
 	
 	/*
-	 * @see TextViewer#getControl
+	 * @see TextViewer#getControl()
 	 */
 	public Control getControl() {
 		if (fComposite != null)
@@ -219,14 +223,14 @@ public class SourceViewer extends TextViewer implements ISourceViewer, ISourceVi
 	}
 	
 	/*
-	 * @see ISourceViewer#setAnnotationHover
+	 * @see ISourceViewer#setAnnotationHover(IAnnotationHover)
 	 */
 	public void setAnnotationHover(IAnnotationHover annotationHover) {
 		fAnnotationHover= annotationHover;
 	}
 	
 	/*
-	 * @see ISourceViewer#configure
+	 * @see ISourceViewer#configure(SourceViewerConfiguration)
 	 */
 	public void configure(SourceViewerConfiguration configuration) {
 		
@@ -293,6 +297,9 @@ public class SourceViewer extends TextViewer implements ISourceViewer, ISourceVi
 		activatePlugins();
 	}
 	
+	/**
+	 * After this method has been executed the caller knows that any installed annotation hover has been installed.
+	 */
 	protected void ensureAnnotationHoverManagerInstalled() {
 		if (fVerticalRuler != null && fAnnotationHover != null && fVerticalRulerHoveringController == null && fHoverControlCreator != null) {
 			fVerticalRulerHoveringController= new AnnotationBarHoverManager(fVerticalRuler, this, fAnnotationHover, fHoverControlCreator);
@@ -300,6 +307,9 @@ public class SourceViewer extends TextViewer implements ISourceViewer, ISourceVi
 		}
 	}
 	
+	/**
+	 * After this method has been executed the caller knows that any installed overview hover has been installed.
+	 */
 	protected void ensureOverviewHoverManagerInstalled() {
 		if (fOverviewRuler != null &&  fAnnotationHover != null  && fOverviewRulerHoveringController == null && fHoverControlCreator != null)	{
 			fOverviewRulerHoveringController= new OverviewRulerHoverManager(fOverviewRuler, this, fAnnotationHover, fHoverControlCreator);
@@ -308,7 +318,7 @@ public class SourceViewer extends TextViewer implements ISourceViewer, ISourceVi
 	}
 	
 	/*
-	 * @see TextViewer#activatePlugins
+	 * @see TextViewer#activatePlugins()
 	 */
 	public void activatePlugins() {
 		ensureAnnotationHoverManagerInstalled();
@@ -375,7 +385,7 @@ public class SourceViewer extends TextViewer implements ISourceViewer, ISourceVi
 	}
 	
 	/*
-	 * @see ISourceViewer#getAnnotationModel
+	 * @see ISourceViewer#getAnnotationModel()
 	 */
 	public IAnnotationModel getAnnotationModel() {
 		if (fVisualAnnotationModel != null)
@@ -384,7 +394,7 @@ public class SourceViewer extends TextViewer implements ISourceViewer, ISourceVi
 	}
 	
 	/*
-	 * @see TextViewer#handleDispose
+	 * @see TextViewer#handleDispose()
 	 */
 	protected void handleDispose() {
 		
@@ -437,7 +447,7 @@ public class SourceViewer extends TextViewer implements ISourceViewer, ISourceVi
 	}
 	
 	/*
-	 * @see ITextOperationTarget#canDoOperation
+	 * @see ITextOperationTarget#canDoOperation(int)
 	 */
 	public boolean canDoOperation(int operation) {
 		
@@ -463,7 +473,7 @@ public class SourceViewer extends TextViewer implements ISourceViewer, ISourceVi
 	}
 	
 	/*
-	 * @see ITextOperationTarget#doOperation
+	 * @see ITextOperationTarget#doOperation(int)
 	 */
 	public void doOperation(int operation) {
 		
@@ -523,14 +533,14 @@ public class SourceViewer extends TextViewer implements ISourceViewer, ISourceVi
 	}
 		
 	/*
-	 * @see ISourceViewer#setRangeIndicator
+	 * @see ISourceViewer#setRangeIndicator(Annotation)
 	 */
 	public void setRangeIndicator(Annotation rangeIndicator) {
 		fRangeIndicator= rangeIndicator;
 	}
 		
 	/*
-	 * @see ISourceViewer#setRangeIndication 	 
+	 * @see ISourceViewer#setRangeIndication(int, int, boolean)
 	 */
 	public void setRangeIndication(int start, int length, boolean moveCursor) {
 		
@@ -544,7 +554,7 @@ public class SourceViewer extends TextViewer implements ISourceViewer, ISourceVi
 	}
 	
 	/*
-	 * @see ISourceViewer#getRangeIndication
+	 * @see ISourceViewer#getRangeIndication()
 	 */
 	public IRegion getRangeIndication() {
 		if (fRangeIndicator != null && fVisualAnnotationModel != null) {
@@ -557,7 +567,7 @@ public class SourceViewer extends TextViewer implements ISourceViewer, ISourceVi
 	}
 	
 	/*
-	 * @see ISourceViewer#removeRangeIndication
+	 * @see ISourceViewer#removeRangeIndication()
 	 */
 	public void removeRangeIndication() {
 		if (fRangeIndicator != null && fVisualAnnotationModel != null)
@@ -584,6 +594,7 @@ public class SourceViewer extends TextViewer implements ISourceViewer, ISourceVi
 	
 	/*
 	 * @see org.eclipse.jface.text.source.ISourceViewerExtension#showAnnotationsOverview(boolean)
+	 * @since 2.1
 	 */
 	public void showAnnotationsOverview(boolean show) {
 		boolean old= fIsOverviewRulerVisible;
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 9f13bde9bfc..1919b3cd867 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
@@ -334,6 +334,13 @@ public final class VerticalRuler implements IVerticalRuler, IVerticalRulerExtens
 		}
 	}
 	
+	/**
+	 * Draws the vertical ruler w/o drawing the Canvas background. Uses
+	 * <code>ITExtViewerExtension3</code> for its implementation. Will replace
+	 * <code>doPaint(GC)</code>.
+	 * 
+	 * @param gc  the gc to draw into
+	 */
 	protected void doPaint1(GC gc) {
 
 		if (fModel == null || fTextViewer == null)
@@ -411,7 +418,6 @@ public final class VerticalRuler implements IVerticalRuler, IVerticalRulerExtens
 			}	
 		}
 	}
-	
 		
 	/**
 	 * Redraws the vertical ruler.
@@ -476,6 +482,14 @@ public final class VerticalRuler implements IVerticalRuler, IVerticalRulerExtens
 		return widgetLine2ModelLine(fTextViewer, line);
 	}
 	
+	/**
+	 * Returns the line of the viewer's document that corresponds to the given widget line.
+	 * 
+	 * @param viewer the viewer
+	 * @param widgetLine the widget line
+	 * @return the corresponding line of the viewer's document
+	 * @since 2.1
+	 */
 	protected final static int widgetLine2ModelLine(ITextViewer viewer, int widgetLine) {
 		
 		if (viewer instanceof ITextViewerExtension3) {
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 762d88af597..401057431de 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
@@ -57,7 +57,7 @@ class VisualAnnotationModel extends AnnotationModel implements IAnnotationModelL
 	}
 	
 	/*
-	 * @see IAnnotationModel#addAnnotationModelListener
+	 * @see IAnnotationModel#addAnnotationModelListener(IAnnotationModelListener)
 	 */
 	public void addAnnotationModelListener(IAnnotationModelListener listener) {
 
@@ -68,7 +68,7 @@ class VisualAnnotationModel extends AnnotationModel implements IAnnotationModelL
 	}
 	
 	/*
-	 * @see IAnnotationModel#connect
+	 * @see IAnnotationModel#connect(IDocument)
 	 */
 	public void connect(IDocument document) {
 		super.connect(document);
@@ -77,7 +77,7 @@ class VisualAnnotationModel extends AnnotationModel implements IAnnotationModelL
 	}
 	
 	/*
-	 * @see IAnnotationModel#disconnect
+	 * @see IAnnotationModel#disconnect(IDocument)
 	 */
 	public void disconnect(IDocument document) {
 		super.disconnect(document);
@@ -86,7 +86,7 @@ class VisualAnnotationModel extends AnnotationModel implements IAnnotationModelL
 	}
 	
 	/*
-	 * @see IAnnotationModel#getAnnotationIterator
+	 * @see IAnnotationModel#getAnnotationIterator()
 	 */
 	public Iterator getAnnotationIterator() {
 		
@@ -107,7 +107,7 @@ class VisualAnnotationModel extends AnnotationModel implements IAnnotationModelL
 	}
 	
 	/*
-	 * @see IAnnotationModel#getPosition
+	 * @see IAnnotationModel#getPosition(Annotation)
 	 */
 	public Position getPosition(Annotation annotation) {
 		
@@ -122,7 +122,7 @@ class VisualAnnotationModel extends AnnotationModel implements IAnnotationModelL
 	}
 		
 	/*
-	 * @see IAnnotationModelListener#modelChanged
+	 * @see IAnnotationModelListener#modelChanged(IAnnotationModel)
 	 */
 	public void modelChanged(IAnnotationModel model) {
 		if (model == fModel) {
@@ -174,7 +174,7 @@ class VisualAnnotationModel extends AnnotationModel implements IAnnotationModelL
 	}
 	
 	/*
-	 * @see IAnnotationModel#removeAnnotationModelListener
+	 * @see IAnnotationModel#removeAnnotationModelListener(IAnnotationModelListener)
 	 */
 	public void removeAnnotationModelListener(IAnnotationModelListener listener) {
 		super.removeAnnotationModelListener(listener);