Fix libcore javadoc errors.

Random's javadoc was pretty random, and Pattern was missing some escaping
in code samples.

Also work round droiddoc bugs that were messing up Formatter and classes
that inherited documentation from Object.

Bug: http://code.google.com/p/android/issues/detail?id=13264
Bug: 3318601

(Cherry-pick from gingerbread.)

Change-Id: I452414aedc04c29127dd0dc3c41e6386bbff1766

4 files changed, 26 insertions, 79 deletions

diff --git a/luni/src/main/java/java/lang/Object.java b/luni/src/main/java/java/lang/Object.java
index 233a7ef..6a979bb 100644
--- a/luni/src/main/java/java/lang/Object.java
+++ b/luni/src/main/java/java/lang/Object.java
@@ -171,7 +171,7 @@ public class Object {
      * Also, no object reference other than null is equal to null.
      *
      * <p>The default implementation returns {@code true} only if {@code this ==
-     * o}. See <a href="#writing_equals">Writing a correct {@code equals} method</a>
+     * o}. See <a href="{@docRoot}/reference/java/lang/Object.html#writing_equals">Writing a correct {@code equals} method</a>
      * if you intend implementing your own {@code equals} method.
      *
      * <p>The general contract for the {@code equals} and {@link
@@ -245,7 +245,7 @@ public class Object {
      * <p>Note that hash values must not change over time unless information used in equals
      * comparisons also changes.
      *
-     * <p>See <a href="#writing_hashCode">Writing a correct {@code hashCode} method</a>
+     * <p>See <a href="{@docRoot}/reference/java/lang/Object.html#writing_hashCode">Writing a correct {@code hashCode} method</a>
      * if you intend implementing your own {@code hashCode} method.
      *
      * @return this object's hash code.
@@ -317,7 +317,7 @@ public class Object {
      * default implementation is equivalent to the following expression:
      * <pre>
      *   getClass().getName() + '@' + Integer.toHexString(hashCode())</pre>
-     * <p>See <a href="#writing_toString">Writing a useful {@code toString} method</a>
+     * <p>See <a href="{@docRoot}/reference/java/lang/Object.html#writing_toString">Writing a useful {@code toString} method</a>
      * if you intend implementing your own {@code toString} method.
      *
      * @return a printable representation of this object.
diff --git a/luni/src/main/java/java/util/Formatter.java b/luni/src/main/java/java/util/Formatter.java
index 6825420..490ae8e 100644
--- a/luni/src/main/java/java/util/Formatter.java
+++ b/luni/src/main/java/java/util/Formatter.java
@@ -65,7 +65,7 @@ import libcore.io.IoUtils;
  * different order in the output than the order in which they were supplied.
  * For example, {@code "%4$s"} formats the fourth argument ({@code 4$}) as a string ({@code s}).
  * It's also possible to reuse an argument with {@code <}. For example,
- * {@code format("%o %<d %<x", 64)} results in {@code "100 64 40"}.
+ * {@code format("%o %&lt;d %&lt;x", 64)} results in {@code "100 64 40"}.
  * <p>
  * <i>Flags</i>. The available flags are:
  * <p>
diff --git a/luni/src/main/java/java/util/Random.java b/luni/src/main/java/java/util/Random.java
index 968350f..dac8eec 100644
--- a/luni/src/main/java/java/util/Random.java
+++ b/luni/src/main/java/java/util/Random.java
@@ -21,11 +21,9 @@ package java.util;
 import java.io.Serializable;
 
 /**
- * This class provides methods that generates pseudo-random numbers of different
- * types, such as {@code int}, {@code long}, {@code double}, and {@code float}.
+ * This class provides methods that return pseudo-random values.
  *
- * @see Properties
- * @see PropertyResourceBundle
+ * @see java.security.SecureRandom
  */
 public class Random implements Serializable {
 
@@ -85,16 +83,7 @@ public class Random implements Serializable {
      * described by Donald E. Knuth in <i>The Art of Computer Programming,
      * Volume 2: Seminumerical Algorithms</i>, section 3.2.1.
      *
-     * @param bits
-     *            number of bits of the returned value.
-     * @return a pseudo-random generated int number.
-     * @see #nextBytes
-     * @see #nextDouble
-     * @see #nextFloat
-     * @see #nextInt()
-     * @see #nextInt(int)
-     * @see #nextGaussian
-     * @see #nextLong
+     * <p>Most applications will want to use one of this class' convenience methods instead.
      */
     protected synchronized int next(int bits) {
         seed = (seed * multiplier + 0xbL) & ((1L << 48) - 1);
@@ -102,22 +91,14 @@ public class Random implements Serializable {
     }
 
     /**
-     * Returns the next pseudo-random, uniformly distributed {@code boolean} value
-     * generated by this generator.
-     *
-     * @return a pseudo-random, uniformly distributed boolean value.
+     * Returns a pseudo-random uniformly distributed {@code boolean}.
      */
     public boolean nextBoolean() {
         return next(1) != 0;
     }
 
     /**
-     * Modifies the {@code byte} array by a random sequence of {@code byte}s generated by this
-     * random number generator.
-     *
-     * @param buf
-     *            non-null array to contain the new random {@code byte}s.
-     * @see #next
+     * Fills {@code buf} with random bytes.
      */
     public void nextBytes(byte[] buf) {
         int rand = 0, count = 0, loop = 0;
@@ -134,37 +115,28 @@ public class Random implements Serializable {
     }
 
     /**
-     * Generates a normally distributed random {@code double} number between 0.0
-     * inclusively and 1.0 exclusively.
-     *
-     * @return a random {@code double} in the range [0.0 - 1.0)
-     * @see #nextFloat
+     * Returns a pseudo-random uniformly distributed {@code double}
+     * in the half-open range [0.0, 1.0).
      */
     public double nextDouble() {
         return ((((long) next(26) << 27) + next(27)) / (double) (1L << 53));
     }
 
     /**
-     * Generates a normally distributed random {@code float} number between 0.0
-     * inclusively and 1.0 exclusively.
-     *
-     * @return float a random {@code float} number between [0.0 and 1.0)
-     * @see #nextDouble
+     * Returns a pseudo-random uniformly distributed {@code float}
+     * in the half-open range [0.0, 1.0).
      */
     public float nextFloat() {
         return (next(24) / 16777216f);
     }
 
     /**
-     * Pseudo-randomly generates (approximately) a normally distributed
-     * {@code double} value with mean 0.0 and a standard deviation value
-     * of {@code 1.0} using the <i>polar method<i> of G. E. P. Box, M.
+     * Returns a pseudo-random (approximately) normally distributed
+     * {@code double} with mean 0.0 and standard deviation 1.0.
+     * This method uses the <i>polar method<i> of G. E. P. Box, M.
      * E. Muller, and G. Marsaglia, as described by Donald E. Knuth in <i>The
      * Art of Computer Programming, Volume 2: Seminumerical Algorithms</i>,
      * section 3.4.1, subsection C, algorithm P.
-     *
-     * @return a random {@code double}
-     * @see #nextDouble
      */
     public synchronized double nextGaussian() {
         if (haveNextNextGaussian) { // if X1 has been returned, return the
@@ -189,26 +161,15 @@ public class Random implements Serializable {
     }
 
     /**
-     * Generates a uniformly distributed 32-bit {@code int} value from
-     * the random number sequence.
-     *
-     * @return a uniformly distributed {@code int} value.
-     * @see java.lang.Integer#MAX_VALUE
-     * @see java.lang.Integer#MIN_VALUE
-     * @see #next
-     * @see #nextLong
+     * Returns a pseudo-random uniformly distributed {@code int}.
      */
     public int nextInt() {
         return next(32);
     }
 
     /**
-     * Returns a new pseudo-random {@code int} value which is uniformly distributed
-     * between 0 (inclusively) and the value of {@code n} (exclusively).
-     *
-     * @param n
-     *            the exclusive upper border of the range [0 - n).
-     * @return a random {@code int}.
+     * Returns a pseudo-random uniformly distributed {@code int}
+     * in the half-open range [0, n).
      */
     public int nextInt(int n) {
         if (n > 0) {
@@ -226,15 +187,7 @@ public class Random implements Serializable {
     }
 
     /**
-     * Generates a uniformly distributed 64-bit integer value from
-     * the random number sequence.
-     *
-     * @return 64-bit random integer.
-     * @see java.lang.Integer#MAX_VALUE
-     * @see java.lang.Integer#MIN_VALUE
-     * @see #next
-     * @see #nextInt()
-     * @see #nextInt(int)
+     * Returns a pseudo-random uniformly distributed {@code long}.
      */
     public long nextLong() {
         return ((long) next(32) << 32) + next(32);
@@ -243,12 +196,6 @@ public class Random implements Serializable {
     /**
      * Modifies the seed using a linear congruential formula presented in <i>The
      * Art of Computer Programming, Volume 2</i>, Section 3.2.1.
-     *
-     * @param seed
-     *            the seed that alters the state of the random number generator.
-     * @see #next
-     * @see #Random()
-     * @see #Random(long)
      */
     public synchronized void setSeed(long seed) {
         this.seed = (seed ^ multiplier) & ((1L << 48) - 1);
diff --git a/luni/src/main/java/java/util/regex/Pattern.java b/luni/src/main/java/java/util/regex/Pattern.java
index 898a582..46984b9 100644
--- a/luni/src/main/java/java/util/regex/Pattern.java
+++ b/luni/src/main/java/java/util/regex/Pattern.java
@@ -25,17 +25,17 @@ import java.io.Serializable;
  * {@link String#matches String.matches}, {@link String#replaceAll String.replaceAll} and
  * {@link String#split String.split} will be preferable, but if you need to do a lot of work
  * with the same regular expression, it may be more efficient to compile it once and reuse it.
- * The {@code Pattern} class and its companion, {@link Matcher}, are also a lot more powerful
- * than the small amount of functionality exposed by {@code String}.
+ * The {@code Pattern} class and its companion, {@link Matcher}, also offer more functionality
+ * than the small amount exposed by {@code String}.
  *
  * <pre>
  * // String convenience methods:
- * boolean sawFailures = s.matches("Failures: \d+");
- * String farewell = s.replaceAll("Hello, (\S+)", "Goodbye, $1");
+ * boolean sawFailures = s.matches("Failures: \\d+");
+ * String farewell = s.replaceAll("Hello, (\\S+)", "Goodbye, $1");
  * String[] fields = s.split(":");
  *
  * // Direct use of Pattern:
- * Pattern p = Pattern.compile("Hello, (\S+)");
+ * Pattern p = Pattern.compile("Hello, (\\S+)");
  * Matcher m = p.matcher(inputString);
  * while (m.find()) { // Find each match in turn; String can't do this.
  *     String name = m.group(1); // Access a submatch group; String can't do this.
@@ -202,7 +202,7 @@ import java.io.Serializable;
  *
  * <h3>Implementation notes</h3>
  *
- * The regular expression implementation used in Android is provided by
+ * <p>The regular expression implementation used in Android is provided by
  * <a href="http://www.icu-project.org">ICU</a>. The notation for the regular
  * expressions is mostly a superset of those used in other Java language
  * implementations. This means that existing applications will normally work as