Merge "Fix @deprecated javadoc orthography."

33 files changed, 87 insertions, 97 deletions

diff --git a/luni/src/main/java/java/io/ByteArrayOutputStream.java b/luni/src/main/java/java/io/ByteArrayOutputStream.java
index ff9c7df..45f217b 100644
--- a/luni/src/main/java/java/io/ByteArrayOutputStream.java
+++ b/luni/src/main/java/java/io/ByteArrayOutputStream.java
@@ -149,7 +149,7 @@ public class ByteArrayOutputStream extends OutputStream {
      *            the high byte of each resulting Unicode character.
      * @return this stream's current contents as a string with the high byte set
      *         to {@code hibyte}.
-     * @deprecated Use {@link #toString()}.
+     * @deprecated Use {@link #toString()} instead.
      */
     @Deprecated
     public String toString(int hibyte) {
diff --git a/luni/src/main/java/java/io/File.java b/luni/src/main/java/java/io/File.java
index 42c1628..6c179f4 100644
--- a/luni/src/main/java/java/io/File.java
+++ b/luni/src/main/java/java/io/File.java
@@ -1082,8 +1082,8 @@ public class File implements Serializable, Comparable<File> {
      * @return a URL for this file.
      * @throws java.net.MalformedURLException
      *             if the path cannot be transformed into a URL.
-     * @deprecated use {@link #toURI} and {@link java.net.URI#toURL} to get
-     * correct escaping of illegal characters.
+     * @deprecated Use {@link #toURI} and {@link java.net.URI#toURL} to
+     * correctly escape illegal characters.
      */
     @Deprecated
     public URL toURL() throws java.net.MalformedURLException {
diff --git a/luni/src/main/java/java/io/LineNumberInputStream.java b/luni/src/main/java/java/io/LineNumberInputStream.java
index 4d1cf14..69d870d 100644
--- a/luni/src/main/java/java/io/LineNumberInputStream.java
+++ b/luni/src/main/java/java/io/LineNumberInputStream.java
@@ -27,7 +27,7 @@ import libcore.io.Streams;
  * When using {@code read}, line terminator sequences are always translated into
  * {@code '\n'}.
  *
- * @deprecated Use {@link LineNumberReader}
+ * @deprecated Use {@link LineNumberReader} instead.
  */
 @Deprecated
 public class LineNumberInputStream extends FilterInputStream {
diff --git a/luni/src/main/java/java/io/ObjectInputStream.java b/luni/src/main/java/java/io/ObjectInputStream.java
index 0b15161..8b684f0 100644
--- a/luni/src/main/java/java/io/ObjectInputStream.java
+++ b/luni/src/main/java/java/io/ObjectInputStream.java
@@ -1404,7 +1404,7 @@ public class ObjectInputStream extends InputStream implements ObjectInput, Objec
      * @return the string read from the source stream.
      * @throws IOException
      *             if an error occurs while reading from the source stream.
-     * @deprecated Use {@link BufferedReader}
+     * @deprecated Use {@link BufferedReader} instead.
      */
     @Deprecated
     public String readLine() throws IOException {
diff --git a/luni/src/main/java/java/io/StreamTokenizer.java b/luni/src/main/java/java/io/StreamTokenizer.java
index a16dc4b..a9e5373 100644
--- a/luni/src/main/java/java/io/StreamTokenizer.java
+++ b/luni/src/main/java/java/io/StreamTokenizer.java
@@ -155,13 +155,13 @@ public class StreamTokenizer {
     /**
      * Constructs a new {@code StreamTokenizer} with {@code is} as source input
      * stream. This constructor is deprecated; instead, the constructor that
-     * takes a {@code Reader} as an arugment should be used.
+     * takes a {@code Reader} as an argument should be used.
      *
      * @param is
      *            the source stream from which to parse tokens.
      * @throws NullPointerException
      *             if {@code is} is {@code null}.
-     * @deprecated Use {@link #StreamTokenizer(Reader)}
+     * @deprecated Use {@link #StreamTokenizer(Reader)} instead.
      */
     @Deprecated
     public StreamTokenizer(InputStream is) {
diff --git a/luni/src/main/java/java/io/StringBufferInputStream.java b/luni/src/main/java/java/io/StringBufferInputStream.java
index 1768abe..686fd83 100644
--- a/luni/src/main/java/java/io/StringBufferInputStream.java
+++ b/luni/src/main/java/java/io/StringBufferInputStream.java
@@ -23,7 +23,7 @@ import java.util.Arrays;
  * A specialized {@link InputStream} that reads bytes from a {@code String} in
  * a sequential manner.
  *
- * @deprecated Use {@link StringReader}
+ * @deprecated Use {@link StringReader} instead.
  */
 @Deprecated
 public class StringBufferInputStream extends InputStream {
diff --git a/luni/src/main/java/java/lang/Character.java b/luni/src/main/java/java/lang/Character.java
index ecdad9f..2f49cf2 100644
--- a/luni/src/main/java/java/lang/Character.java
+++ b/luni/src/main/java/java/lang/Character.java
@@ -2839,7 +2839,7 @@ public final class Character implements Serializable, Comparable<Character> {
      *            the character to check.
      * @return {@code true} if {@code c} is a Java letter; {@code false}
      *         otherwise.
-     * @deprecated Use {@link #isJavaIdentifierStart(char)}
+     * @deprecated Use {@link #isJavaIdentifierStart(char)} instead.
      */
     @Deprecated
     public static boolean isJavaLetter(char c) {
@@ -2854,7 +2854,7 @@ public final class Character implements Serializable, Comparable<Character> {
      *            the character to check.
      * @return {@code true} if {@code c} is a Java letter or digit;
      *         {@code false} otherwise.
-     * @deprecated Use {@link #isJavaIdentifierPart(char)}
+     * @deprecated Use {@link #isJavaIdentifierPart(char)} instead.
      */
     @Deprecated
     public static boolean isJavaLetterOrDigit(char c) {
@@ -2968,7 +2968,7 @@ public final class Character implements Serializable, Comparable<Character> {
      *            the character to check.
      * @return {@code true} if {@code c} is a Java space; {@code false}
      *         otherwise.
-     * @deprecated Use {@link #isWhitespace(char)}
+     * @deprecated Use {@link #isWhitespace(char)} instead.
      */
     @Deprecated
     public static boolean isSpace(char c) {
diff --git a/luni/src/main/java/java/lang/Runtime.java b/luni/src/main/java/java/lang/Runtime.java
index 88d4cc6..8538f8a 100644
--- a/luni/src/main/java/java/lang/Runtime.java
+++ b/luni/src/main/java/java/lang/Runtime.java
@@ -483,7 +483,7 @@ public class Runtime {
      * @param stream
      *            the input stream to localize.
      * @return the localized input stream.
-     * @deprecated Use {@link InputStreamReader}.
+     * @deprecated Use {@link InputStreamReader} instead.
      */
     @Deprecated
     public InputStream getLocalizedInputStream(InputStream stream) {
@@ -503,7 +503,7 @@ public class Runtime {
      * @param stream
      *            the output stream to localize.
      * @return the localized output stream.
-     * @deprecated Use {@link OutputStreamWriter}.
+     * @deprecated Use {@link OutputStreamWriter} instead.
      */
     @Deprecated
     public OutputStream getLocalizedOutputStream(OutputStream stream) {
diff --git a/luni/src/main/java/java/lang/SecurityManager.java b/luni/src/main/java/java/lang/SecurityManager.java
index 98e92cc..55ade78 100644
--- a/luni/src/main/java/java/lang/SecurityManager.java
+++ b/luni/src/main/java/java/lang/SecurityManager.java
@@ -30,7 +30,7 @@ import java.security.Permission;
  */
 public class SecurityManager {
     /**
-     * @deprecated Use {@link #checkPermission}
+     * @deprecated Use {@link #checkPermission} instead.
      */
     @Deprecated
     protected boolean inCheck;
@@ -64,7 +64,7 @@ public class SecurityManager {
     public void checkMulticast(InetAddress maddr) { }
 
     /**
-     * @deprecated use {@link #checkMulticast(java.net.InetAddress)}
+     * @deprecated use {@link #checkMulticast(java.net.InetAddress)} instead.
      */
     @Deprecated public void checkMulticast(InetAddress maddr, byte ttl) { }
 
@@ -99,41 +99,41 @@ public class SecurityManager {
     public void checkWrite(String file) { }
 
     /**
-     * @deprecated Use {@link #checkPermission}.
+     * @deprecated Use {@link #checkPermission} instead.
      */
     @Deprecated public boolean getInCheck() { return inCheck; }
 
     protected Class[] getClassContext() { return null; }
 
     /**
-     * @deprecated Use {@link #checkPermission}.
+     * @deprecated Use {@link #checkPermission} instead.
      */
     @Deprecated protected ClassLoader currentClassLoader() { return null; }
 
     /**
-     * @deprecated Use {@link #checkPermission}.
+     * @deprecated Use {@link #checkPermission} instead.
      */
     @Deprecated protected int classLoaderDepth() {
         return -1;
     }
 
     /**
-     * @deprecated Use {@link #checkPermission}.
+     * @deprecated Use {@link #checkPermission} instead.
      */
     @Deprecated protected Class<?> currentLoadedClass() { return null; }
 
     /**
-     * @deprecated Use {@link #checkPermission}.
+     * @deprecated Use {@link #checkPermission} instead.
      */
     @Deprecated protected int classDepth(String name) { return -1; }
 
     /**
-     * @deprecated Use {@link #checkPermission}.
+     * @deprecated Use {@link #checkPermission} instead.
      */
     @Deprecated protected boolean inClass(String name) { return false; }
 
     /**
-     * @deprecated Use {@link #checkPermission}
+     * @deprecated Use {@link #checkPermission} instead.
      */
     @Deprecated protected boolean inClassLoader() { return false; }
 
diff --git a/luni/src/main/java/java/lang/System.java b/luni/src/main/java/java/lang/System.java
index da1e460..c825118 100644
--- a/luni/src/main/java/java/lang/System.java
+++ b/luni/src/main/java/java/lang/System.java
@@ -585,7 +585,7 @@ public final class System {
      *
      * @param flag
      *            the flag determines if finalization on exit is enabled.
-     * @deprecated this method is unsafe.
+     * @deprecated This method is unsafe.
      */
     @SuppressWarnings("deprecation")
     @Deprecated
diff --git a/luni/src/main/java/java/net/DatagramSocketImpl.java b/luni/src/main/java/java/net/DatagramSocketImpl.java
index 7b00b4c..097eb17 100644
--- a/luni/src/main/java/java/net/DatagramSocketImpl.java
+++ b/luni/src/main/java/java/net/DatagramSocketImpl.java
@@ -94,7 +94,7 @@ public abstract class DatagramSocketImpl implements SocketOptions {
      * @throws IOException
      *             if an error occurs while getting the time-to-live option
      *             value.
-     * @deprecated Replaced by {@link #getTimeToLive}
+     * @deprecated Use {@link #getTimeToLive} instead.
      * @see #getTimeToLive()
      */
     @Deprecated
@@ -225,7 +225,7 @@ public abstract class DatagramSocketImpl implements SocketOptions {
      *            &lt;= 255.
      * @throws IOException
      *             if an error occurs while setting the option.
-     * @deprecated Replaced by {@link #setTimeToLive}
+     * @deprecated Use {@link #setTimeToLive} instead.
      * @see #setTimeToLive(int)
      */
     @Deprecated
diff --git a/luni/src/main/java/java/net/HttpURLConnection.java b/luni/src/main/java/java/net/HttpURLConnection.java
index 573dde6..3086bdb 100644
--- a/luni/src/main/java/java/net/HttpURLConnection.java
+++ b/luni/src/main/java/java/net/HttpURLConnection.java
@@ -475,7 +475,7 @@ public abstract class HttpURLConnection extends URLConnection {
     /**
      * Numeric status code, 500: Internal error
      *
-     * @deprecated Use {@link #HTTP_INTERNAL_ERROR}
+     * @deprecated Use {@link #HTTP_INTERNAL_ERROR} instead.
      */
     @Deprecated
     public static final int HTTP_SERVER_ERROR = 500;
diff --git a/luni/src/main/java/java/net/MulticastSocket.java b/luni/src/main/java/java/net/MulticastSocket.java
index 498a132..6f4a582 100644
--- a/luni/src/main/java/java/net/MulticastSocket.java
+++ b/luni/src/main/java/java/net/MulticastSocket.java
@@ -127,7 +127,7 @@ public class MulticastSocket extends DatagramSocket {
      * Returns the time-to-live (TTL) for multicast packets sent on this socket.
      *
      * @throws IOException if an error occurs.
-     * @deprecated Replaced by {@link #getTimeToLive}
+     * @deprecated Use {@link #getTimeToLive} instead.
      */
     @Deprecated
     public byte getTTL() throws IOException {
@@ -239,7 +239,7 @@ public class MulticastSocket extends DatagramSocket {
      * deprecated because it modifies the TTL socket option for this socket twice on each call.
      *
      * @throws IOException if an error occurs.
-     * @deprecated use {@link #setTimeToLive}.
+     * @deprecated Use {@link #setTimeToLive} instead.
      */
     @Deprecated
     public void send(DatagramPacket packet, byte ttl) throws IOException {
@@ -314,7 +314,7 @@ public class MulticastSocket extends DatagramSocket {
      * Valid TTL values are between 0 and 255 inclusive.
      *
      * @throws IOException if an error occurs.
-     * @deprecated Replaced by {@link #setTimeToLive}
+     * @deprecated Use {@link #setTimeToLive} instead.
      */
     @Deprecated
     public void setTTL(byte ttl) throws IOException {
diff --git a/luni/src/main/java/java/net/URLConnection.java b/luni/src/main/java/java/net/URLConnection.java
index 18a264e..74c15ce 100644
--- a/luni/src/main/java/java/net/URLConnection.java
+++ b/luni/src/main/java/java/net/URLConnection.java
@@ -347,7 +347,7 @@ public abstract class URLConnection {
     /**
      * Returns null.
      *
-     * @deprecated Use {@link #getRequestProperty}
+     * @deprecated Use {@link #getRequestProperty} instead.
      */
     @Deprecated
     public static String getDefaultRequestProperty(String field) {
@@ -829,7 +829,7 @@ public abstract class URLConnection {
     /**
      * Does nothing.
      *
-     * @deprecated Use {@link URLConnection#setRequestProperty(String, String)}.
+     * @deprecated Use {@link URLConnection#setRequestProperty(String, String)} instead.
      */
     @Deprecated
     public static void setDefaultRequestProperty(String field, String value) {
diff --git a/luni/src/main/java/java/net/URLDecoder.java b/luni/src/main/java/java/net/URLDecoder.java
index f21de7d..23dd8d0 100644
--- a/luni/src/main/java/java/net/URLDecoder.java
+++ b/luni/src/main/java/java/net/URLDecoder.java
@@ -38,7 +38,7 @@ public class URLDecoder {
      * @param s
      *            the encoded string.
      * @return the decoded clear-text representation of the given string.
-     * @deprecated use {@link #decode(String, String)} instead.
+     * @deprecated Use {@link #decode(String, String)} instead.
      */
     @Deprecated
     public static String decode(String s) {
diff --git a/luni/src/main/java/java/net/URLEncoder.java b/luni/src/main/java/java/net/URLEncoder.java
index 5dd85b0..527c017 100644
--- a/luni/src/main/java/java/net/URLEncoder.java
+++ b/luni/src/main/java/java/net/URLEncoder.java
@@ -43,7 +43,7 @@ public class URLEncoder {
     /**
      * Equivalent to {@code encode(s, "UTF-8")}.
      *
-     * @deprecated use {@link #encode(String, String)} instead.
+     * @deprecated Use {@link #encode(String, String)} instead.
      */
     @Deprecated
     public static String encode(String s) {
diff --git a/luni/src/main/java/java/net/URLStreamHandler.java b/luni/src/main/java/java/net/URLStreamHandler.java
index 4a04b6f..8a6c264 100644
--- a/luni/src/main/java/java/net/URLStreamHandler.java
+++ b/luni/src/main/java/java/net/URLStreamHandler.java
@@ -222,7 +222,7 @@ public abstract class URLStreamHandler {
      *            the file component.
      * @param ref
      *            the reference.
-     * @deprecated use setURL(URL, String String, int, String, String, String,
+     * @deprecated Use setURL(URL, String String, int, String, String, String,
      *             String, String) instead.
      */
     @Deprecated
diff --git a/luni/src/main/java/java/security/Certificate.java b/luni/src/main/java/java/security/Certificate.java
index afec0d3..1d410a1 100644
--- a/luni/src/main/java/java/security/Certificate.java
+++ b/luni/src/main/java/java/security/Certificate.java
@@ -27,7 +27,7 @@ import java.io.OutputStream;
  * validity of itself. It's in the responsibility of the application to verify
  * the validity of its certificates.
  *
- * @deprecated Replaced by behavior in {@link java.security.cert}
+ * @deprecated Use {@link java.security.cert.Certificate} instead.
  * @see java.security.cert.Certificate
  */
 @Deprecated
diff --git a/luni/src/main/java/java/security/Identity.java b/luni/src/main/java/java/security/Identity.java
index 6e5b8a3..f0eef5d 100644
--- a/luni/src/main/java/java/security/Identity.java
+++ b/luni/src/main/java/java/security/Identity.java
@@ -25,9 +25,8 @@ import libcore.util.Objects;
 /**
  * {@code Identity} represents an identity like a person or a company.
  *
- * @deprecated The functionality of this class has been replace by
- *             {@link Principal}, {@link KeyStore} and the {@code
- *             java.security.cert} package.
+ * @deprecated Use {@link Principal}, {@link KeyStore} and the {@code java.security.cert} package
+ * instead.
  */
 @Deprecated
 public abstract class Identity implements Principal, Serializable {
diff --git a/luni/src/main/java/java/security/IdentityScope.java b/luni/src/main/java/java/security/IdentityScope.java
index 1e344fd..ee17b58 100644
--- a/luni/src/main/java/java/security/IdentityScope.java
+++ b/luni/src/main/java/java/security/IdentityScope.java
@@ -23,9 +23,8 @@ import java.util.Enumeration;
 /**
  * {@code IdentityScope} represents a scope for {@link Identity} objects.
  *
- * @deprecated The functionality of this class has been replace by
- *             {@link Principal}, {@link KeyStore} and the {@code
- *             java.security.cert} package.
+ * @deprecated Use {@link Principal}, {@link KeyStore} and the {@code java.security.cert} package
+ * instead.
  */
 @Deprecated
 public abstract class IdentityScope extends Identity {
diff --git a/luni/src/main/java/java/security/Security.java b/luni/src/main/java/java/security/Security.java
index 0876136..0b6961b 100644
--- a/luni/src/main/java/java/security/Security.java
+++ b/luni/src/main/java/java/security/Security.java
@@ -86,8 +86,7 @@ public final class Security {
      * @param propName
      *            the name of the property.
      * @return value of the property.
-     * @deprecated Use {@link AlgorithmParameters} and {@link KeyFactory}
-     *             instead.
+     * @deprecated Use {@link AlgorithmParameters} and {@link KeyFactory} instead.
      */
     @Deprecated
     public static String getAlgorithmProperty(String algName, String propName) {
diff --git a/luni/src/main/java/java/security/Signature.java b/luni/src/main/java/java/security/Signature.java
index b2bd122..0372c33 100644
--- a/luni/src/main/java/java/security/Signature.java
+++ b/luni/src/main/java/java/security/Signature.java
@@ -523,7 +523,7 @@ public abstract class Signature extends SignatureSpi {
      * @throws InvalidParameterException
      *             if the parameter is invalid, already set or is not allowed to
      *             be changed.
-     * @deprecated Use {@link #setParameter(AlgorithmParameterSpec)}
+     * @deprecated Use {@link #setParameter(AlgorithmParameterSpec)} instead.
      */
     @Deprecated
     public final void setParameter(String param, Object value)
@@ -565,7 +565,7 @@ public abstract class Signature extends SignatureSpi {
      *         null}.
      * @throws InvalidParameterException
      *             if {@code param} is not a valid parameter for this {@code
-     *             Signature} or an other error occures.
+     *             Signature} or an other error occurs.
      * @deprecated There is no generally accepted parameter naming convention.
      */
     @Deprecated
diff --git a/luni/src/main/java/java/security/Signer.java b/luni/src/main/java/java/security/Signer.java
index b892090..8f8ef06 100644
--- a/luni/src/main/java/java/security/Signer.java
+++ b/luni/src/main/java/java/security/Signer.java
@@ -21,9 +21,8 @@ package java.security;
  * {@link Signer} represents an identity (individual or corporation) that owns a
  * private key and the corresponding public key.
  *
- * @deprecated Replaced by behavior in {@link java.security.cert
- *             java.security.cert} package and {@link java.security.Principal
- *             Principal}
+ * @deprecated Use the {@link java.security.cert java.security.cert} package
+ * and {@link java.security.Principal} instead.
  */
 @Deprecated
 public abstract class Signer extends Identity {
diff --git a/luni/src/main/java/java/sql/CallableStatement.java b/luni/src/main/java/java/sql/CallableStatement.java
index 5bd9c52..162841d 100644
--- a/luni/src/main/java/java/sql/CallableStatement.java
+++ b/luni/src/main/java/java/sql/CallableStatement.java
@@ -111,8 +111,7 @@ public interface CallableStatement extends PreparedStatement {
      *         the parameter in question is an SQL {@code NULL}.
      * @throws SQLException
      *             if a database error occurs.
-     * @deprecated Use {@link #getBigDecimal(int)} or
-     *             {@link #getBigDecimal(String)}
+     * @deprecated Use {@link #getBigDecimal(int)} or {@link #getBigDecimal(String)} instead.
      */
     @Deprecated
     public BigDecimal getBigDecimal(int parameterIndex, int scale)
diff --git a/luni/src/main/java/java/sql/Date.java b/luni/src/main/java/java/sql/Date.java
index 34ca5bd..4aac326 100644
--- a/luni/src/main/java/java/sql/Date.java
+++ b/luni/src/main/java/java/sql/Date.java
@@ -41,7 +41,7 @@ public class Date extends java.util.Date {
      * Constructs a {@code Date} object corresponding to the supplied year,
      * month and day.
      *
-     * @deprecated Use the constructor {@link #Date(long)}.
+     * @deprecated Use the constructor {@link #Date(long)} instead.
      * @param theYear
      *            the year, specified as the year minus 1900. Must be in the
      *            range {@code [0,8099]}.
diff --git a/luni/src/main/java/java/sql/DriverManager.java b/luni/src/main/java/java/sql/DriverManager.java
index 550ccae..58fc068 100644
--- a/luni/src/main/java/java/sql/DriverManager.java
+++ b/luni/src/main/java/java/sql/DriverManager.java
@@ -281,7 +281,7 @@ public class DriverManager {
      * Gets the log {@code PrintStream} used by the {@code DriverManager} and
      * all the JDBC Drivers.
      *
-     * @deprecated use {@link #getLogWriter()} instead.
+     * @deprecated Use {@link #getLogWriter()} instead.
      * @return the {@code PrintStream} used for logging activities.
      */
     @Deprecated
diff --git a/luni/src/main/java/java/sql/ResultSet.java b/luni/src/main/java/java/sql/ResultSet.java
index 64ecb59..12b681a 100644
--- a/luni/src/main/java/java/sql/ResultSet.java
+++ b/luni/src/main/java/java/sql/ResultSet.java
@@ -298,8 +298,7 @@ public interface ResultSet extends Wrapper, AutoCloseable {
      * Gets the value of a column specified by column index as a {@code
      * java.math.BigDecimal}.
      *
-     * @deprecated use {@link #getBigDecimal(int)} or
-     *             {@link #getBigDecimal(String)}
+     * @deprecated Use {@link #getBigDecimal(int)} or {@link #getBigDecimal(String)} instead.
      * @param columnIndex
      *            the index of the column to read.
      * @param scale
@@ -328,8 +327,7 @@ public interface ResultSet extends Wrapper, AutoCloseable {
      * Gets the value of a column specified by column name, as a {@code
      * java.math.BigDecimal}.
      *
-     * @deprecated use {@link #getBigDecimal(int)} or
-     *             {@link #getBigDecimal(String)}
+     * @deprecated Use {@link #getBigDecimal(int)} or {@link #getBigDecimal(String)} instead.
      * @param columnName
      *            the name of the column to read.
      * @param scale
@@ -1050,7 +1048,7 @@ public interface ResultSet extends Wrapper, AutoCloseable {
      * Gets the value of the column as an {@code InputStream} of unicode
      * characters.
      *
-     * @deprecated Use {@link #getCharacterStream}.
+     * @deprecated Use {@link #getCharacterStream} instead.
      * @param columnIndex
      *            the index of the column to read.
      * @return an {@code InputStream} holding the value of the column. {@code
@@ -1065,7 +1063,7 @@ public interface ResultSet extends Wrapper, AutoCloseable {
      * Gets the value of the column as an {@code InputStream} of Unicode
      * characters.
      *
-     * @deprecated Use {@link #getCharacterStream}
+     * @deprecated Use {@link #getCharacterStream} instead.
      * @param columnName
      *            the name of the column to read.
      * @return an {@code InputStream} holding the value of the column. {@code
diff --git a/luni/src/main/java/java/sql/Time.java b/luni/src/main/java/java/sql/Time.java
index 913379c..c6e2f20 100644
--- a/luni/src/main/java/java/sql/Time.java
+++ b/luni/src/main/java/java/sql/Time.java
@@ -39,7 +39,7 @@ public class Time extends Date {
      * <p>
      * The result is undefined if any argument is out of bounds.
      *
-     * @deprecated Use the constructor {@link #Time(long)}.
+     * @deprecated Use the constructor {@link #Time(long)} instead.
      * @param theHour
      *            a value in the range {@code [0,23]}.
      * @param theMinute
@@ -67,7 +67,7 @@ public class Time extends Date {
 
     /**
      * @deprecated This method is deprecated and must not be used. An SQL
-     *             {@code Time} object does not have a {@code Date} component.
+     *             {@code Time} object does not have a date component.
      * @return does not return anything.
      * @throws IllegalArgumentException
      *             if this method is called.
@@ -81,7 +81,7 @@ public class Time extends Date {
 
     /**
      * @deprecated This method is deprecated and must not be used. An SQL
-     *             {@code Time} object does not have a <i>Day</i> component.
+     *             {@code Time} object does not have a day component.
      * @return does not return anything.
      * @throws IllegalArgumentException
      *             if this method is called.
@@ -95,7 +95,7 @@ public class Time extends Date {
 
     /**
      * @deprecated This method is deprecated and must not be used. An SQL
-     *             {@code Time} object does not have a <i>Month</i> component.
+     *             {@code Time} object does not have a month component.
      * @return does not return anything.
      * @throws IllegalArgumentException
      *             if this method is called.
@@ -109,7 +109,7 @@ public class Time extends Date {
 
     /**
      * @deprecated This method is deprecated and must not be used. An SQL
-     *             {@code Time} object does not have a <i>Year</i> component.
+     *             {@code Time} object does not have a year component.
      * @return does not return anything.
      * @throws IllegalArgumentException
      *             if this method is called.
@@ -123,7 +123,7 @@ public class Time extends Date {
 
     /**
      * @deprecated This method is deprecated and must not be used. An SQL
-     *             {@code Time} object does not have a {@code Date} component.
+     *             {@code Time} object does not have a date component.
      * @throws IllegalArgumentException
      *             if this method is called.
      */
@@ -136,7 +136,7 @@ public class Time extends Date {
 
     /**
      * @deprecated This method is deprecated and must not be used. An SQL
-     *             {@code Time} object does not have a <i>Month</i> component.
+     *             {@code Time} object does not have a month component.
      * @throws IllegalArgumentException
      *             if this method is called.
      */
@@ -149,7 +149,7 @@ public class Time extends Date {
 
     /**
      * @deprecated This method is deprecated and must not be used. An SQL
-     *             {@code Time} object does not have a <i>Year</i> component.
+     *             {@code Time} object does not have a year component.
      * @throws IllegalArgumentException
      *             if this method is called.
      */
diff --git a/luni/src/main/java/java/sql/Timestamp.java b/luni/src/main/java/java/sql/Timestamp.java
index 2e6d3d9..f35fa9b 100644
--- a/luni/src/main/java/java/sql/Timestamp.java
+++ b/luni/src/main/java/java/sql/Timestamp.java
@@ -57,7 +57,7 @@ public class Timestamp extends Date {
      * supplied values for <i>Year</i>, <i>Month</i>, <i>Date</i>, <i>Hour</i>,
      * <i>Minutes</i>, <i>Seconds</i> and <i>Nanoseconds</i>.
      *
-     * @deprecated Use the constructor {@link #Timestamp(long)}.
+     * @deprecated Use the constructor {@link #Timestamp(long)} instead.
      * @param theYear
      *            specified as the year minus 1900.
      * @param theMonth
diff --git a/luni/src/main/java/java/util/Date.java b/luni/src/main/java/java/util/Date.java
index da9f296..b4de055 100644
--- a/luni/src/main/java/java/util/Date.java
+++ b/luni/src/main/java/java/util/Date.java
@@ -69,8 +69,7 @@ public class Date implements Serializable, Cloneable, Comparable<Date> {
      * @param day
      *            the day of the month, 1 - 31.
      *
-     * @deprecated use
-     *             {@link GregorianCalendar#GregorianCalendar(int, int, int)}
+     * @deprecated Use {@link GregorianCalendar#GregorianCalendar(int, int, int)} instead.
      */
     @Deprecated
     public Date(int year, int month, int day) {
@@ -94,8 +93,7 @@ public class Date implements Serializable, Cloneable, Comparable<Date> {
      * @param minute
      *            the minute of the hour, 0 - 59.
      *
-     * @deprecated use
-     *             {@link GregorianCalendar#GregorianCalendar(int, int, int, int, int)}
+     * @deprecated Use {@link GregorianCalendar#GregorianCalendar(int, int, int, int, int)} instead.
      */
     @Deprecated
     public Date(int year, int month, int day, int hour, int minute) {
@@ -121,8 +119,8 @@ public class Date implements Serializable, Cloneable, Comparable<Date> {
      * @param second
      *            the second of the minute, 0 - 59.
      *
-     * @deprecated use
-     *             {@link GregorianCalendar#GregorianCalendar(int, int, int, int, int, int)}
+     * @deprecated Use {@link GregorianCalendar#GregorianCalendar(int, int, int, int, int, int)}
+     * instead.
      */
     @Deprecated
     public Date(int year, int month, int day, int hour, int minute, int second) {
@@ -149,7 +147,7 @@ public class Date implements Serializable, Cloneable, Comparable<Date> {
      * @param string
      *            the String to parse.
      *
-     * @deprecated use {@link DateFormat}
+     * @deprecated Use {@link DateFormat} instead.
      */
     @Deprecated
     public Date(String string) {
@@ -238,7 +236,7 @@ public class Date implements Serializable, Cloneable, Comparable<Date> {
      *
      * @return the day of the month.
      *
-     * @deprecated use {@code Calendar.get(Calendar.DATE)}
+     * @deprecated Use {@code Calendar.get(Calendar.DATE)} instead.
      */
     @Deprecated
     public int getDate() {
@@ -250,7 +248,7 @@ public class Date implements Serializable, Cloneable, Comparable<Date> {
      *
      * @return the day of the week.
      *
-     * @deprecated use {@code Calendar.get(Calendar.DAY_OF_WEEK)}
+     * @deprecated Use {@code Calendar.get(Calendar.DAY_OF_WEEK)} instead.
      */
     @Deprecated
     public int getDay() {
@@ -262,7 +260,7 @@ public class Date implements Serializable, Cloneable, Comparable<Date> {
      *
      * @return the hour of the day.
      *
-     * @deprecated use {@code Calendar.get(Calendar.HOUR_OF_DAY)}
+     * @deprecated Use {@code Calendar.get(Calendar.HOUR_OF_DAY)} instead.
      */
     @Deprecated
     public int getHours() {
@@ -274,7 +272,7 @@ public class Date implements Serializable, Cloneable, Comparable<Date> {
      *
      * @return the minutes.
      *
-     * @deprecated use {@code Calendar.get(Calendar.MINUTE)}
+     * @deprecated Use {@code Calendar.get(Calendar.MINUTE)} instead.
      */
     @Deprecated
     public int getMinutes() {
@@ -286,7 +284,7 @@ public class Date implements Serializable, Cloneable, Comparable<Date> {
      *
      * @return the month.
      *
-     * @deprecated use {@code Calendar.get(Calendar.MONTH)}
+     * @deprecated Use {@code Calendar.get(Calendar.MONTH)} instead.
      */
     @Deprecated
     public int getMonth() {
@@ -298,7 +296,7 @@ public class Date implements Serializable, Cloneable, Comparable<Date> {
      *
      * @return the seconds.
      *
-     * @deprecated use {@code Calendar.get(Calendar.SECOND)}
+     * @deprecated Use {@code Calendar.get(Calendar.SECOND)} instead.
      */
     @Deprecated
     public int getSeconds() {
@@ -320,8 +318,7 @@ public class Date implements Serializable, Cloneable, Comparable<Date> {
      *
      * @return the timezone offset in minutes of the default {@code TimeZone}.
      *
-     * @deprecated use
-     *             {@code (Calendar.get(Calendar.ZONE_OFFSET) + Calendar.get(Calendar.DST_OFFSET)) / 60000}
+     * @deprecated Use {@code (Calendar.get(Calendar.ZONE_OFFSET) + Calendar.get(Calendar.DST_OFFSET)) / 60000} instead.
      */
     @Deprecated
     public int getTimezoneOffset() {
@@ -334,7 +331,7 @@ public class Date implements Serializable, Cloneable, Comparable<Date> {
      *
      * @return the year - 1900.
      *
-     * @deprecated use {@code Calendar.get(Calendar.YEAR) - 1900}
+     * @deprecated Use {@code Calendar.get(Calendar.YEAR) - 1900} instead.
      */
     @Deprecated
     public int getYear() {
@@ -376,7 +373,7 @@ public class Date implements Serializable, Cloneable, Comparable<Date> {
      *            the String to parse.
      * @return the millisecond value parsed from the String.
      *
-     * @deprecated use {@link DateFormat}
+     * @deprecated Use {@link DateFormat} instead.
      */
     @Deprecated
     public static long parse(String string) {
@@ -569,7 +566,7 @@ public class Date implements Serializable, Cloneable, Comparable<Date> {
      * @param day
      *            the day of the month.
      *
-     * @deprecated use {@code Calendar.set(Calendar.DATE, day)}
+     * @deprecated Use {@code Calendar.set(Calendar.DATE, day)} instead.
      */
     @Deprecated
     public void setDate(int day) {
@@ -584,7 +581,7 @@ public class Date implements Serializable, Cloneable, Comparable<Date> {
      * @param hour
      *            the hour of the day.
      *
-     * @deprecated use {@code Calendar.set(Calendar.HOUR_OF_DAY, hour)}
+     * @deprecated Use {@code Calendar.set(Calendar.HOUR_OF_DAY, hour)} instead.
      */
     @Deprecated
     public void setHours(int hour) {
@@ -599,7 +596,7 @@ public class Date implements Serializable, Cloneable, Comparable<Date> {
      * @param minute
      *            the minutes.
      *
-     * @deprecated use {@code Calendar.set(Calendar.MINUTE, minute)}
+     * @deprecated Use {@code Calendar.set(Calendar.MINUTE, minute)} instead.
      */
     @Deprecated
     public void setMinutes(int minute) {
@@ -614,7 +611,7 @@ public class Date implements Serializable, Cloneable, Comparable<Date> {
      * @param month
      *            the month.
      *
-     * @deprecated use {@code Calendar.set(Calendar.MONTH, month)}
+     * @deprecated Use {@code Calendar.set(Calendar.MONTH, month)} instead.
      */
     @Deprecated
     public void setMonth(int month) {
@@ -629,7 +626,7 @@ public class Date implements Serializable, Cloneable, Comparable<Date> {
      * @param second
      *            the seconds.
      *
-     * @deprecated use {@code Calendar.set(Calendar.SECOND, second)}
+     * @deprecated Use {@code Calendar.set(Calendar.SECOND, second)} instead.
      */
     @Deprecated
     public void setSeconds(int second) {
@@ -655,7 +652,7 @@ public class Date implements Serializable, Cloneable, Comparable<Date> {
      * @param year
      *            the year since 1900.
      *
-     * @deprecated use {@code Calendar.set(Calendar.YEAR, year + 1900)}
+     * @deprecated Use {@code Calendar.set(Calendar.YEAR, year + 1900)} instead.
      */
     @Deprecated
     public void setYear(int year) {
@@ -668,7 +665,7 @@ public class Date implements Serializable, Cloneable, Comparable<Date> {
      * Returns the string representation of this {@code Date} in GMT in the format
      * {@code "22 Jun 1999 13:02:00 GMT"}.
      *
-     * @deprecated use {@link DateFormat}
+     * @deprecated Use {@link DateFormat} instead.
      */
     @Deprecated
     public String toGMTString() {
@@ -683,7 +680,7 @@ public class Date implements Serializable, Cloneable, Comparable<Date> {
     /**
      * Returns the string representation of this {@code Date} for the default {@code Locale}.
      *
-     * @deprecated use {@link DateFormat}
+     * @deprecated Use {@link DateFormat} instead.
      */
     @Deprecated
     public String toLocaleString() {
@@ -749,7 +746,7 @@ public class Date implements Serializable, Cloneable, Comparable<Date> {
      *            the second of the minute, 0 - 59.
      * @return the date and time in GMT in milliseconds.
      *
-     * @deprecated use: <code>
+     * @deprecated Use code like this instead:<code>
      *  Calendar cal = new GregorianCalendar(TimeZone.getTimeZone("GMT"));
      *  cal.set(year + 1900, month, day, hour, minute, second);
      *  cal.getTime().getTime();</code>
diff --git a/luni/src/main/java/java/util/Properties.java b/luni/src/main/java/java/util/Properties.java
index 57c6a00..cd19295 100644
--- a/luni/src/main/java/java/util/Properties.java
+++ b/luni/src/main/java/java/util/Properties.java
@@ -486,7 +486,7 @@ public class Properties extends Hashtable<Object, Object> {
      * @throws ClassCastException if the key or value of a mapping is not a
      *                String.
      * @deprecated This method ignores any {@code IOException} thrown while
-     *             writing -- use {@link #store} instead for better exception
+     *             writing &mdash; use {@link #store} instead for better exception
      *             handling.
      */
     @Deprecated
diff --git a/luni/src/main/java/java/util/logging/Logger.java b/luni/src/main/java/java/util/logging/Logger.java
index 1567b8d..3f2b787 100644
--- a/luni/src/main/java/java/util/logging/Logger.java
+++ b/luni/src/main/java/java/util/logging/Logger.java
@@ -91,8 +91,8 @@ public class Logger {
 
     /**
      * The global logger is provided as convenience for casual use.
-     * @deprecated deadlock-prone. Use {@code Logger.getLogger(Logger.GLOBAL_LOGGER_NAME)} as
-     * a direct replacement, but see the discussion of how to use {@code Logger} in the class
+     * @deprecated This is deadlock-prone. Use {@code Logger.getLogger(Logger.GLOBAL_LOGGER_NAME)}
+     * as a direct replacement, but read the discussion of how to use {@link Logger} in the class
      * documentation.
      */
     @Deprecated
diff --git a/luni/src/main/java/libcore/io/IoUtils.java b/luni/src/main/java/libcore/io/IoUtils.java
index d307088..c0c9e7e 100644
--- a/luni/src/main/java/libcore/io/IoUtils.java
+++ b/luni/src/main/java/libcore/io/IoUtils.java
@@ -138,7 +138,7 @@ public final class IoUtils {
      * Deliberately ignores errors, on the assumption that test cleanup is only
      * supposed to be best-effort.
      *
-     * @deprecated Use createTemporaryDirectory instead.
+     * @deprecated Use {@link #createTemporaryDirectory} instead.
      */
     public static void deleteContents(File dir) throws IOException {
         File[] files = dir.listFiles();