1 files changed, 22 insertions, 36 deletions

diff --git a/luni/src/main/java/java/util/regex/MatchResult.java b/luni/src/main/java/java/util/regex/MatchResult.java
index 76c17a8..c77206d 100644
--- a/luni/src/main/java/java/util/regex/MatchResult.java
+++ b/luni/src/main/java/java/util/regex/MatchResult.java
@@ -19,79 +19,65 @@ package java.util.regex;
 
 /**
  * Holds the results of a successful match of a {@link Pattern} against a
- * given string. The result is divided into groups, with one group for each
- * pair of parentheses in the regular expression and an additional group for
- * the whole regular expression. The start, end, and contents of each group
- * can be queried.
- *
- * @see Matcher
- * @see Matcher#toMatchResult()
+ * given string. Typically this is an instance of {@link Matcher}, but
+ * since that's a mutable class it's also possible to freeze its current
+ * state using {@link Matcher#toMatchResult}.
  */
 public interface MatchResult {
 
     /**
      * Returns the index of the first character following the text that matched
      * the whole regular expression.
-     *
-     * @return the character index.
      */
     int end();
 
     /**
      * Returns the index of the first character following the text that matched
-     * a given group.
-     *
-     * @param group
-     *            the group, ranging from 0 to groupCount() - 1, with 0
-     *            representing the whole pattern.
-     *
-     * @return the character index.
+     * a given group. See {@link #group} for an explanation of group indexes.
      */
     int end(int group);
 
     /**
      * Returns the text that matched the whole regular expression.
-     *
-     * @return the text.
      */
     String group();
 
     /**
      * Returns the text that matched a given group of the regular expression.
      *
-     * @param group
-     *            the group, ranging from 0 to groupCount() - 1, with 0
-     *            representing the whole pattern.
+     * <p>Explicit capturing groups in the pattern are numbered left to right in order
+     * of their <i>opening</i> parenthesis, starting at 1.
+     * The special group 0 represents the entire match (as if the entire pattern is surrounded
+     * by an implicit capturing group).
+     * For example, "a((b)c)" matching "abc" would give the following groups:
+     * <pre>
+     * 0 "abc"
+     * 1 "bc"
+     * 2 "b"
+     * </pre>
      *
-     * @return the text that matched the group.
+     * <p>An optional capturing group that failed to match as part of an overall
+     * successful match (for example, "a(b)?c" matching "ac") returns null.
+     * A capturing group that matched the empty string (for example, "a(b?)c" matching "ac")
+     * returns the empty string.
      */
     String group(int group);
 
     /**
-     * Returns the number of groups in the result, which is always equal to
+     * Returns the number of groups in the results, which is always equal to
      * the number of groups in the original regular expression.
-     *
-     * @return the number of groups.
      */
     int groupCount();
 
     /**
-     * Returns the index of the first character of the text that matched
-     * the whole regular expression.
-     *
-     * @return the character index.
+     * Returns the index of the first character of the text that matched the
+     * whole regular expression.
      */
     int start();
 
     /**
      * Returns the index of the first character of the text that matched a given
-     * group.
-     *
-     * @param group
-     *            the group, ranging from 0 to groupCount() - 1, with 0
-     *            representing the whole pattern.
-     *
-     * @return the character index.
+     * group. See {@link #group} for an explanation of group indexes.
      */
     int start(int group);
 }