Polished Javadoc (see bug 40580 for details)

2 files changed, 9 insertions, 12 deletions

diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/DefaultCharacterPairMatcher.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/DefaultCharacterPairMatcher.java
index 1327c8a0340..4983562119f 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/DefaultCharacterPairMatcher.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/DefaultCharacterPairMatcher.java
@@ -167,14 +167,13 @@ public class DefaultCharacterPairMatcher implements ICharacterPairMatcher, IChar
 	}
 
 	/**
-	 * Computes the adjustment in the start offset for the purpose of finding a matching peer. The
-	 * adjustment is non-zero only when the selection length is one and the selection covers a
-	 * character matched by the matcher.
+	 * Computes the adjustment in the start offset for the purpose of finding a matching peer. This
+	 * is required as the direction of selection can be right-to-left or left-to-right.
 	 * 
 	 * @param document the document to work on
 	 * @param offset the start offset
 	 * @param length the selection length
-	 * @return the start offset adjustment
+	 * @return the start offset adjustment which can be -1, 0 or +1
 	 * @since 3.8
 	 */
 	private int getOffsetAdjustment(IDocument document, int offset, int length) {
diff --git a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ICharacterPairMatcherExtension.java b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ICharacterPairMatcherExtension.java
index 32ceac7fe9d..ef87038a5b1 100644
--- a/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ICharacterPairMatcherExtension.java
+++ b/org.eclipse.jface.text/src/org/eclipse/jface/text/source/ICharacterPairMatcherExtension.java
@@ -25,16 +25,15 @@ import org.eclipse.jface.text.IRegion;
 public interface ICharacterPairMatcherExtension {
 
 	/**
-	 * Starting with the selected character or a character close to the given <code>offset</code>,
-	 * the matcher searches for the matching peer character and if it finds one, returns the minimal
-	 * region of the document that contains both characters.
+	 * Starting at the given offset (i.e. length 0) or the selected character, the matcher searches
+	 * for the matching peer character and if it finds one, returns the minimal region of the
+	 * document that contains both characters.
 	 * 
 	 * @param document the document to work on
 	 * @param offset the start offset
-	 * @param length the selection length. The length can be negative indicating right-to-left
-	 *            selection.
+	 * @param length the selection length which can be negative indicating right-to-left selection
 	 * @return the minimal region containing the peer characters or <code>null</code> if there is no
-	 *         peer character.
+	 *         peer character
 	 */
 	IRegion match(IDocument document, int offset, int length);
 
@@ -45,8 +44,7 @@ public interface ICharacterPairMatcherExtension {
 	 * 
 	 * @param document the document to work on
 	 * @param offset the start offset
-	 * @param length the selection length. The length can be negative indicating right-to-left
-	 *            selection.
+	 * @param length the selection length which can be negative indicating right-to-left selection
 	 * @return the minimal region containing the peer characters or <code>null</code> if there is no
 	 *         enclosing pair
 	 */