harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r772785 [9/12] - /harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/
Date Thu, 07 May 2009 21:43:44 GMT
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Scanner.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Scanner.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Scanner.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Scanner.java Thu May  7 21:43:41 2009
@@ -39,22 +39,24 @@
 /**
  * A parser that parses a text string of primitive types and strings with the
  * help of regular expressions. It supports localized numbers and various
- * radixes.
- * 
- * The input is broken into tokens by the delimiter pattern, which is whitespace
- * by default. The primitive types can be obtained via corresponding next*
- * methods. If the token is not in a valid format, an InputMismatchException is
- * thrown.
- * 
- * For example: <code>Scanner s = new Scanner("1A true");
- * System.out.println(s.nextInt(16)); System.out.println(s.nextBoolean());</code>
- * The result: <code>26 true</code>
- * 
- * A scanner can also find or skip specific patterns with no regard to the
+ * radixes. The input is broken into tokens by the delimiter pattern, which is
+ * whitespace by default. The primitive types can be obtained via corresponding
+ * next* methods. If the token is not in a valid format, an
+ * {@code InputMismatchException} is thrown.
+ * <p>
+ * For example:
+ * <pre>
+ * Scanner s = new Scanner("1A true");
+ * System.out.println(s.nextInt(16));
+ * System.out.println(s.nextBoolean());
+ * </pre>
+ * <p>
+ * Yields the result: {@code 26 true}
+ * <p>A {@code Scanner} can also find or skip specific patterns without regard for the
  * delimiter. All these methods and the various next* and hasNext* methods may
  * block.
- * 
- * The Scanner class is not thread-safe.
+ * <p>
+ * The {@code Scanner} class is not thread-safe.
  */
 public final class Scanner implements Iterator<String> {
 
@@ -150,30 +152,30 @@
     }
 
     /**
-     * Constructs a scanner that uses File as its input. The default charset is
-     * applied when reading the file.
+     * Creates a {@code Scanner} with the specified {@code File} as input. The default charset
+     * is applied when reading the file.
      * 
      * @param src
-     *            the file to be scanned
+     *            the file to be scanned.
      * @throws FileNotFoundException
-     *             if the specified file is not found
+     *             if the specified file does not exist.
      */
     public Scanner(File src) throws FileNotFoundException {
         this(src, Charset.defaultCharset().name());
     }
 
     /**
-     * Constructs a scanner that uses File as its input. The specified charset
+     * Creates a {@code Scanner} with the specified {@code File} as input. The specified charset
      * is applied when reading the file.
      * 
      * @param src
-     *            the file to be scanned
+     *            the file to be scanned.
      * @param charsetName
-     *            the name of the encoding type of the file
+     *            the name of the encoding type of the file.
      * @throws FileNotFoundException
-     *             if the specified file is not found
+     *             if the specified file does not exist.
      * @throws IllegalArgumentException
-     *             if the specified coding does not exist
+     *             if the specified coding does not exist.
      */
     public Scanner(File src, String charsetName) throws FileNotFoundException {
         if (null == src) {
@@ -199,10 +201,10 @@
     }
 
     /**
-     * Constructs a scanner that uses String as its input.
+     * Creates a {@code Scanner} on the specified string.
      * 
      * @param src
-     *            the string to be scanned
+     *            the string to be scanned.
      */
     public Scanner(String src) {
         input = new StringReader(src);
@@ -210,26 +212,26 @@
     }
 
     /**
-     * Constructs a scanner that uses InputStream as its input. The default
-     * charset is applied when decoding the input.
+     * Creates a {@code Scanner} on the specified {@code InputStream}. The default charset is
+     * applied when decoding the input.
      * 
      * @param src
-     *            the input stream to be scanned
+     *            the {@code InputStream} to be scanned.
      */
     public Scanner(InputStream src) {
         this(src, Charset.defaultCharset().name());
     }
 
     /**
-     * Constructs a scanner that uses InputStream as its input. The specified
-     * charset is applied when decoding the input.
+     * Creates a {@code Scanner} on the specified {@code InputStream}. The specified charset is
+     * applied when decoding the input.
      * 
      * @param src
-     *            the input stream to be scanned
+     *            the {@code InputStream} to be scanned.
      * @param charsetName
-     *            the encoding type of the input stream
+     *            the encoding type of the {@code InputStream}.
      * @throws IllegalArgumentException
-     *             if the specified character set is not found
+     *             if the specified character set is not found.
      */
     public Scanner(InputStream src, String charsetName) {
         if (null == src) {
@@ -245,10 +247,10 @@
     }
 
     /**
-     * Constructs a scanner that uses Readable as its input.
+     * Creates a {@code Scanner} with the specified {@code Readable} as input.
      * 
      * @param src
-     *            the Readable to be scanned
+     *            the {@code Readable} to be scanned.
      */
     public Scanner(Readable src) {
         if (null == src) {
@@ -259,26 +261,26 @@
     }
 
     /**
-     * Constructs a scanner that uses ReadableByteChannel as its input. The
-     * default charset is applied when decoding the input.
+     * Creates a {@code Scanner} with the specified {@code ReadableByteChannel} as
+     * input. The default charset is applied when decoding the input.
      * 
      * @param src
-     *            the ReadableByteChannel to be scanned
+     *            the {@code ReadableByteChannel} to be scanned.
      */
     public Scanner(ReadableByteChannel src) {
         this(src, Charset.defaultCharset().name());
     }
 
     /**
-     * Constructs a scanner that uses ReadableByteChannel as its input. The
-     * specified charset is applied when decoding the input.
+     * Creates a {@code Scanner} with the specified {@code ReadableByteChannel} as
+     * input. The specified charset is applied when decoding the input.
      * 
      * @param src
-     *            the ReadableByteChannel to be scanned
+     *            the {@code ReadableByteChannel} to be scanned.
      * @param charsetName
-     *            the encoding type of the content in the ReadableByteChannel
+     *            the encoding type of the content.
      * @throws IllegalArgumentException
-     *             if the specified character set is not found
+     *             if the specified character set is not found.
      */
     public Scanner(ReadableByteChannel src, String charsetName) {
         if (null == src) {
@@ -294,10 +296,12 @@
     }
 
     /**
-     * Closes the underlying input if the input implements Closeable. If the
-     * scanner has been closed, this method will take no effect. The scanning
-     * operation after calling this method will throw IllegalStateException
+     * Closes this {@code Scanner} and the underlying input if the input implements
+     * {@code Closeable}. If the {@code Scanner} has been closed, this method will have
+     * no effect. Any scanning operation called after calling this method will throw
+     * an {@code IllegalStateException}.
      * 
+     * @see Closeable
      */
     public void close() {
         if (closed) {
@@ -314,28 +318,28 @@
     }
 
     /**
-     * Returns the <code>Pattern</code> in use by this scanner.
+     * Returns the delimiter {@code Pattern} in use by this {@code Scanner}.
      * 
-     * @return the <code>Pattern</code> presently in use by this scanner
+     * @return the delimiter {@code Pattern} in use by this {@code Scanner}.
      */
     public Pattern delimiter() {
         return delimiter;
     }
 
     /**
-     * Tries to find the pattern in input. Delimiters are ignored. If the
+     * Tries to find the pattern in the input. Delimiters are ignored. If the
      * pattern is found before line terminator, the matched string will be
-     * returned, and the scanner will advance to the end of the matched string.
-     * Otherwise, null will be returned and the scanner will not advance the
-     * input. When waiting for input, the scanner may be blocked.
-     * 
-     * All the input may be cached if no line terminator exists in the buffer.
+     * returned, and the {@code Scanner} will advance to the end of the matched string.
+     * Otherwise, {@code null} will be returned and the {@code Scanner} will not advance.
+     * When waiting for input, the {@code Scanner} may be blocked. All the
+     * input may be cached if no line terminator exists in the buffer.
      * 
      * @param pattern
-     *            the pattern used to match input
-     * @return the matched string
+     *            the pattern to find in the input.
+     * @return the matched string or {@code null} if the pattern is not found
+     *         before the next line terminator.
      * @throws IllegalStateException
-     *             if the scanner is closed
+     *             if the {@code Scanner} is closed.
      */
     public String findInLine(Pattern pattern) {
         checkClosed();
@@ -416,52 +420,54 @@
     }
 
     /**
-     * Tries to find the pattern compiled from the specified string. The
-     * delimiter will be ignored. It is the same as invoke
-     * findInLine(Pattern.compile(pattern))
+     * Compiles the pattern string and tries to find a substing matching it in the input data. The
+     * delimiter will be ignored. This is the same as invoking
+     * {@code findInLine(Pattern.compile(pattern))}.
      * 
      * @param pattern
-     *            a string used to construct a pattern which in turn used to
-     *            match input
-     * @return the matched string
+     *            a string used to construct a pattern which is in turn used to
+     *            match a substring of the input data.
+     * @return the matched string or {@code null} if the pattern is not found
+     *         before the next line terminator.
      * @throws IllegalStateException
-     *             if the scanner is closed
+     *             if the {@code Scanner} is closed.
+     * @see #findInLine(Pattern)
      */
     public String findInLine(String pattern) {
         return findInLine(Pattern.compile(pattern));
     }
 
     /**
-     * Tries to find the pattern in input from current position to the specified
+     * Tries to find the pattern in the input between the current position and the specified
      * horizon. Delimiters are ignored. If the pattern is found, the matched
-     * string will be returned, and the scanner will advance to the end of the
-     * matched string. Otherwise, null will be returned and scanner will not
-     * advance the input. When waiting for input, the scanner may be blocked.
-     * 
-     * Scanner will never search exceed horizon code points from current
-     * position. The position of horizon does have effects on the result of
-     * match. For example, when input is "123", and current position is at zero,
-     * findWithinHorizon(Pattern.compile("\\p{Digit}{3}"), 2) will return null.
-     * While findWithinHorizon(Pattern.compile("\\p{Digit}{3}"), 3) will return
-     * "123". Horizon is treated as a transparent, non-anchoring bound. (refer
-     * to {@link Matcher#useTransparentBounds} and
-     * {@link Matcher#useAnchoringBounds})
-     * 
-     * Horizon whose value is zero will be ignored and the whole input will be
-     * used for search. Under this situation, all the input may be cached.
-     * 
-     * An IllegalArgumentException will be thrown out if horizon is less than
-     * zero.
-     * 
+     * string will be returned, and the {@code Scanner} will advance to the end of the
+     * matched string. Otherwise, null will be returned and {@code Scanner} will not
+     * advance. When waiting for input, the {@code Scanner} may be blocked.
+     * <p>
+     * The {@code Scanner}'s search will never go more than {@code horizon} code points from current
+     * position. The position of {@code horizon} does have an effect on the result of the
+     * match. For example, when the input is "123" and current position is at zero,
+     * {@code findWithinHorizon(Pattern.compile("\\p&#123;Digit&#125;&#123;3&#125;"), 2)}
+     * will return {@code null}. While
+     * {@code findWithinHorizon(Pattern.compile("\\p&#123;Digit&#125;&#123;3&#125;"), 3)}
+     * will return {@code "123"}. {@code horizon} is treated as a transparent,
+     * non-anchoring bound. (refer to
+     * {@link Matcher#useTransparentBounds(boolean)} and
+     * {@link Matcher#useAnchoringBounds(boolean)})
+     * <p>
+     * A {@code horizon} whose value is zero will be ignored and the whole input will be
+     * used for search. In this situation, all the input may be cached.
+     *
      * @param pattern
-     *            the pattern used to scan
+     *            the pattern used to scan.
      * @param horizon
-     *            the search limit
-     * @return the matched string
+     *            the search limit.
+     * @return the matched string or {@code null} if the pattern is not found
+     *         within the specified {@code horizon}.
      * @throws IllegalStateException
-     *             if the scanner is closed
+     *             if the {@code Scanner} is closed.
      * @throws IllegalArgumentException
-     *             if horizon is less than zero
+     *             if {@code horizon} is less than zero.
      */
     public String findWithinHorizon(Pattern pattern, int horizon) {
         checkClosed();
@@ -523,48 +529,50 @@
     }
 
     /**
-     * Tries to find the pattern in input from current position to the specified
-     * horizon. Delimiters are ignored.
-     * 
-     * It is the same as invoke findWithinHorizon(Pattern.compile(pattern)).
+     * Tries to find the pattern in the input between the current position and the specified
+     * {@code horizon}. Delimiters are ignored. This call is the same as invoking
+     * {@code findWithinHorizon(Pattern.compile(pattern))}.
      * 
      * @param pattern
-     *            the pattern used to scan
+     *            the pattern used to scan.
      * @param horizon
-     *            the search limit
-     * @return the matched string
+     *            the search limit.
+     * @return the matched string, or {@code null} if the pattern is not found
+     *         within the specified horizon.
      * @throws IllegalStateException
-     *             if the scanner is closed
+     *             if the {@code Scanner} is closed.
      * @throws IllegalArgumentException
-     *             if horizon is less than zero
+     *             if {@code horizon} is less than zero.
+     * @see #findWithinHorizon(Pattern, int)
      */
     public String findWithinHorizon(String pattern, int horizon) {
         return findWithinHorizon(Pattern.compile(pattern), horizon);
     }
 
     /**
-     * Returns true if this scanner has one or more tokens remaining to parse.
-     * Will block if the data is still being read.
+     * Returns whether this {@code Scanner} has one or more tokens remaining to parse.
+     * This method will block if the data is still being read.
      * 
-     * @return true if this scanner has one or more tokens remaining
+     * @return {@code true} if this {@code Scanner} has one or more tokens remaining,
+     *         otherwise {@code false}.
      * @throws IllegalStateException
-     *             if the scanner has been closed
+     *             if the {@code Scanner} has been closed.
      */
     public boolean hasNext() {
         return hasNext(ANY_PATTERN);
     }
 
     /**
-     * Returns true if this scanner has one or more tokens remaining to parse
-     * and the next token matches the given pattern. Will block if the data is
+     * Returns whether this {@code Scanner} has one or more tokens remaining to parse
+     * and the next token matches the given pattern. This method will block if the data is
      * still being read.
      * 
      * @param pattern
-     *            the pattern to check for
-     * @return true if this scanner has more tokens and the next token matches
-     *         the pattern
+     *            the pattern to check for.
+     * @return {@code true} if this {@code Scanner} has more tokens and the next token
+     *         matches the pattern, {@code false} otherwise.
      * @throws IllegalStateException
-     *             if the scanner has been closed
+     *             if the {@code Scanner} has been closed.
      */
     public boolean hasNext(Pattern pattern) {
         checkClosed();
@@ -590,31 +598,30 @@
     }
 
     /**
-     * Returns true if this scanner has one or more tokens remaining to parse
-     * and the next token matches a pattern compiled from the given string. Will
-     * block if the data is still being read.
-     * 
-     * Equivalent to <code>hasNext(Pattern.compile(pattern))</code>.
+     * Returns {@code true} if this {@code Scanner} has one or more tokens remaining to parse
+     * and the next token matches a pattern compiled from the given string. This method will
+     * block if the data is still being read. This call is equivalent to
+     * {@code hasNext(Pattern.compile(pattern))}.
      * 
      * @param pattern
-     *            the string representation of the pattern to check for
-     * @return true if this scanner has more tokens and the next token matches
-     *         the pattern
+     *            the string specifying the pattern to scan for
+     * @return {@code true} if the specified pattern matches this {@code Scanner}'s
+     *         next token, {@code false} otherwise.
      * @throws IllegalStateException
-     *             if the scanner has been closed
+     *             if the {@code Scanner} has been closed.
      */
     public boolean hasNext(String pattern) {
         return hasNext(Pattern.compile(pattern));
     }
 
     /**
-     * Returns true if this scanner's next token can be translated into a valid
-     * BigDecimal.
+     * Returns whether the next token can be translated into a valid
+     * {@code BigDecimal}.
      * 
-     * @return true if the next token in this scanner's input can be translated
-     *         into a valid BigDecimal
+     * @return {@code true} if the next token can be translated into a valid
+     *         {@code BigDecimal}, otherwise {@code false.}
      * @throws IllegalStateException
-     *             if the scanner has been closed
+     *             if the {@code Scanner} has been closed.
      */
     public boolean hasNextBigDecimal() {
         Pattern floatPattern = getFloatPattern();
@@ -633,28 +640,29 @@
     }
 
     /**
-     * Returns true if this scanner's next token can be translated into a valid
-     * BigInteger in the default radix.
+     * Returns whether the next token can be translated into a valid
+     * {@code BigInteger} in the default radix.
      * 
-     * @return true if the next token in this scanner's input can be translated
-     *         into a valid BigInteger
+     * @return {@code true} if the next token can be translated into a valid
+     *         {@code BigInteger}, otherwise {@code false}.
      * @throws IllegalStateException
-     *             if the scanner has been closed
+     *             if the {@code Scanner} has been closed.
      */
     public boolean hasNextBigInteger() {
         return hasNextBigInteger(integerRadix);
     }
 
     /**
-     * Returns true if this scanner's next token can be translated into a valid
-     * BigInteger in the specified radix.
+     * Returns whether the next token can be translated into a valid
+     * {@code BigInteger} in the specified radix.
      * 
      * @param radix
-     *            the radix used to translate the token into a BigInteger
-     * @return true if the next token in this scanner's input can be translated
-     *         into a valid BigInteger
+     *            the radix used to translate the token into a
+     *            {@code BigInteger}.
+     * @return {@code true} if the next token can be translated into a valid
+     *         {@code BigInteger}, otherwise {@code false}.
      * @throws IllegalStateException
-     *             if the scanner has been closed
+     *             if the {@code Scanner} has been closed.
      */
     public boolean hasNextBigInteger(int radix) {
         Pattern integerPattern = getIntegerPattern(radix);
@@ -673,41 +681,42 @@
     }
 
     /**
-     * Returns true if this scanner's next token can be translated into a valid
-     * boolean value.
+     * Returns whether the next token can be translated into a valid
+     * {@code boolean} value.
      * 
-     * @return true if the next token in this scanner's input can be translated
-     *         into a valid boolean value
+     * @return {@code true} if the next token can be translated into a valid
+     *         {@code boolean} value, otherwise {@code false}.
      * @throws IllegalStateException
-     *             if the scanner has been closed
+     *             if the {@code Scanner} has been closed.
      */
     public boolean hasNextBoolean() {
         return hasNext(BOOLEAN_PATTERN);
     }
 
     /**
-     * Returns true if this scanner's next token can be translated into a valid
-     * byte value in the default radix.
+     * Returns whether the next token can be translated into a valid
+     * {@code byte} value in the default radix.
      * 
-     * @return true if the next token in this scanner's input can be translated
-     *         into a valid byte value
+     * @return {@code true} if the next token can be translated into a valid
+     *         {@code byte} value, otherwise {@code false}.
      * @throws IllegalStateException
-     *             if the scanner has been closed
+     *             if the {@code Scanner} has been closed.
      */
     public boolean hasNextByte() {
         return hasNextByte(integerRadix);
     }
 
     /**
-     * Returns true if this scanner's next token can be translated into a valid
-     * byte value in the specified radix.
+     * Returns whether the next token can be translated into a valid
+     * {@code byte} value in the specified radix.
      * 
      * @param radix
-     *            the radix used to translate the token into a byte value
-     * @return true if the next token in this scanner's input can be translated
-     *         into a valid byte value
+     *            the radix used to translate the token into a {@code byte}
+     *            value
+     * @return {@code true} if the next token can be translated into a valid
+     *         {@code byte} value, otherwise {@code false}.
      * @throws IllegalStateException
-     *             if the scanner has been closed
+     *             if the {@code Scanner} has been closed.
      */
     public boolean hasNextByte(int radix) {
         Pattern integerPattern = getIntegerPattern(radix);
@@ -726,13 +735,13 @@
     }
 
     /**
-     * Returns true if this scanner's next token can be translated into a valid
-     * double value.
+     * Returns whether the next token translated into a valid {@code double}
+     * value.
      * 
-     * @return true if the next token in this scanner's input can be translated
-     *         into a valid double value
+     * @return {@code true} if the next token can be translated into a valid
+     *         {@code double} value, otherwise {@code false}.
      * @throws IllegalStateException
-     *             if the scanner has been closed
+     *             if the {@code Scanner} has been closed.
      */
     public boolean hasNextDouble() {
         Pattern floatPattern = getFloatPattern();
@@ -751,13 +760,13 @@
     }
 
     /**
-     * Returns true if this scanner's next token can be translated into a valid
-     * float value.
+     * Returns whether the next token can be translated into a valid
+     * {@code float} value.
      * 
-     * @return true if the next token in this scanner's input can be translated
-     *         into a valid float value
+     * @return {@code true} if the next token can be translated into a valid
+     *         {@code float} value, otherwise {@code false}.
      * @throws IllegalStateException
-     *             if the scanner has been closed
+     *             if the {@code Scanner} has been closed.
      */
     public boolean hasNextFloat() {
         Pattern floatPattern = getFloatPattern();
@@ -776,28 +785,30 @@
     }
 
     /**
-     * Returns true if this scanner's next token can be translated into a valid
-     * int value in the default radix.
+     * Returns whether the next token can be translated into a valid {@code int}
+     * value in the default radix.
      * 
-     * @return true if the next token in this scanner's input can be translated
-     *         into a valid int value
+     * @return {@code true} if the next token can be translated into a valid
+     *         {@code int} value, otherwise {@code false}.
      * @throws IllegalStateException
-     *             if the scanner has been closed
+     *             if the {@code Scanner} has been closed,
      */
     public boolean hasNextInt() {
         return hasNextInt(integerRadix);
     }
 
     /**
-     * Returns true if this scanner's next token can be translated into a valid
-     * int value in the specified radix.
+     * Returns whether the next token can be translated into a valid {@code int}
+     * value in the specified radix.
      * 
      * @param radix
-     *            the radix used to translate the token into an int value
-     * @return true if the next token in this scanner's input can be translated
-     *         into a valid int value
+     *            the radix used to translate the token into an {@code int}
+     *            value.
+     * @return {@code true} if the next token in this {@code Scanner}'s input can be
+     *         translated into a valid {@code int} value, otherwise
+     *         {@code false}.
      * @throws IllegalStateException
-     *             if the scanner has been closed
+     *             if the {@code Scanner} has been closed.
      */
     public boolean hasNextInt(int radix) {
         Pattern integerPattern = getIntegerPattern(radix);
@@ -816,13 +827,13 @@
     }
 
     /**
-     * Returns true if there is another line in the input. Otherwise, returns
-     * false. When waiting for input, the scanner may be blocked.
+     * Returns whether there is a line terminator in the input.
+     * This method may block.
      * 
-     * @return true if there is another line in the input. Otherwise, false will
-     *         be returned.
+     * @return {@code true} if there is a line terminator in the input,
+     *         otherwise, {@code false}.
      * @throws IllegalStateException
-     *             if the scanner is closed
+     *             if the {@code Scanner} is closed.
      */
     public boolean hasNextLine() {
         checkClosed();
@@ -852,28 +863,29 @@
     }
 
     /**
-     * Returns true if this scanner's next token can be translated into a valid
-     * long value in the default radix.
+     * Returns whether the next token can be translated into a valid
+     * {@code long} value in the default radix.
      * 
-     * @return true if the next token in this scanner's input can be translated
-     *         into a valid long value
+     * @return {@code true} if the next token can be translated into a valid
+     *         {@code long} value, otherwise {@code false}.
      * @throws IllegalStateException
-     *             if the scanner has been closed
+     *             if the {@code Scanner} has been closed.
      */
     public boolean hasNextLong() {
         return hasNextLong(integerRadix);
     }
 
     /**
-     * Returns true if this scanner's next token can be translated into a valid
-     * long value in the specified radix.
+     * Returns whether the next token can be translated into a valid
+     * {@code long} value in the specified radix.
      * 
      * @param radix
-     *            the radix used to translate the token into a long value
-     * @return true if the next token in this scanner's input can be translated
-     *         into a valid long value
+     *            the radix used to translate the token into a {@code long}
+     *            value.
+     * @return {@code true} if the next token can be translated into a valid
+     *         {@code long} value, otherwise {@code false}.
      * @throws IllegalStateException
-     *             if the scanner has been closed
+     *             if the {@code Scanner} has been closed.
      */
     public boolean hasNextLong(int radix) {
         Pattern integerPattern = getIntegerPattern(radix);
@@ -892,28 +904,29 @@
     }
 
     /**
-     * Returns true if this scanner's next token can be translated into a valid
-     * short value in the default radix.
+     * Returns whether the next token can be translated into a valid
+     * {@code short} value in the default radix.
      * 
-     * @return true if the next token in this scanner's input can be translated
-     *         into a valid short value
+     * @return {@code true} if the next token can be translated into a valid
+     *         {@code short} value, otherwise {@code false}.
      * @throws IllegalStateException
-     *             if the scanner has been closed
+     *             if the {@code Scanner} has been closed.
      */
     public boolean hasNextShort() {
         return hasNextShort(integerRadix);
     }
 
     /**
-     * Returns true if this scanner's next token can be translated into a valid
-     * short value in the specified radix.
+     * Returns whether the next token can be translated into a valid
+     * {@code short} value in the specified radix.
      * 
      * @param radix
-     *            the radix used to translate the token into a short value
-     * @return true if the next token in this scanner's input can be translated
-     *         into a valid short value
+     *            the radix used to translate the token into a {@code short}
+     *            value.
+     * @return {@code true} if the next token can be translated into a valid
+     *         {@code short} value, otherwise {@code false}.
      * @throws IllegalStateException
-     *             if the scanner has been closed
+     *             if the {@code Scanner} has been closed.
      */
     public boolean hasNextShort(int radix) {
         Pattern integerPattern = getIntegerPattern(radix);
@@ -932,41 +945,34 @@
     }
 
     /**
-     * Returns the last IOException thrown when reading the underlying input. If
-     * no exception is thrown, return null.
+     * Returns the last {@code IOException} that was raised while reading from the underlying
+     * input.
      * 
-     * @return the last IOException thrown
+     * @return the last thrown {@code IOException}, or {@code null} if none was thrown.
      */
     public IOException ioException() {
         return lastIOException;
     }
 
     /**
-     * Return the locale of this scanner.
+     * Return the {@code Locale} of this {@code Scanner}.
      * 
-     * @return the locale of this scanner
+     * @return the {@code Locale} of this {@code Scanner}.
      */
     public Locale locale() {
         return locale;
     }
 
     /**
-     * Returns the match result of this scanner's last match operation.This
-     * method throws IllegalStateException if no match operation has been
-     * performed, or if the last match was unsuccessful.
-     * 
-     * The various nextXXX methods of Scanner provide a match result if they do
-     * not complete with throwing an exception. For example, after an invocation
-     * of the nextBoolean() method which returned a boolean value, this method
-     * returns a match result for the search of the Boolean regular expression
-     * defined above. In the same way,the findInLine(java.lang.String),
-     * findWithinHorizon(java.lang.String, int), and
-     * skip(java.util.regex.Pattern) methods will provide a match result if they
-     * are successful.
+     * Returns the result of the last matching operation.
+     * <p>
+     * The next* and find* methods return the match result in the case of a
+     * successful match.
      * 
-     * @return the match result of the last match operation
+     * @return the match result of the last successful match operation
      * @throws IllegalStateException
-     *             if the match result is not available
+     *             if the match result is not available, of if the last match
+     *             was not successful.
      */
     public MatchResult match() {
         if (!matchSuccessful) {
@@ -978,13 +984,13 @@
     /**
      * Returns the next token. The token will be both prefixed and postfixed by
      * the delimiter that is currently being used (or a string that matches the
-     * delimiter pattern). Will block if input is being read.
+     * delimiter pattern). This method will block if input is being read.
      * 
-     * @return the next token
+     * @return the next complete token.
      * @throws IllegalStateException
-     *             if this scanner has been closed
+     *             if this {@code Scanner} has been closed.
      * @throws NoSuchElementException
-     *             if input has been exhausted
+     *             if input has been exhausted.
      */
     public String next() {
         return next(ANY_PATTERN);
@@ -993,18 +999,18 @@
     /**
      * Returns the next token if it matches the specified pattern. The token
      * will be both prefixed and postfixed by the delimiter that is currently
-     * being used (or a string that matches the delimiter pattern). Will block
+     * being used (or a string that matches the delimiter pattern). This method will block
      * if input is being read.
      * 
      * @param pattern
-     *            the pattern to check for
-     * @return the next token
+     *            the specified pattern to scan.
+     * @return the next token.
      * @throws IllegalStateException
-     *             if this scanner has been closed
+     *             if this {@code Scanner} has been closed.
      * @throws NoSuchElementException
-     *             if input has been exhausted
+     *             if input has been exhausted.
      * @throws InputMismatchException
-     *             if the next token does not match the pattern given
+     *             if the next token does not match the pattern given.
      */
     public String next(Pattern pattern) {
         checkClosed();
@@ -1029,44 +1035,42 @@
     /**
      * Returns the next token if it matches the specified pattern. The token
      * will be both prefixed and postfixed by the delimiter that is currently
-     * being used (or a string that matches the delimiter pattern). Will block
-     * if input is being read.
-     * 
-     * Equivalent to <code>next(Pattern.compile(pattern))</code>.
+     * being used (or a string that matches the delimiter pattern). This method will block
+     * if input is being read. Calling this methos is equivalent to
+     * {@code next(Pattern.compile(pattern))}.
      * 
      * @param pattern
-     *            the string representation of the pattern to check for
-     * @return the next token
+     *            the string specifying the pattern to scan for.
+     * @return the next token.
      * @throws IllegalStateException
-     *             if this scanner has been closed
+     *             if this {@code Scanner} has been closed.
      * @throws NoSuchElementException
-     *             if input has been exhausted
+     *             if input has been exhausted.
      * @throws InputMismatchException
-     *             if the next token does not match the pattern given
+     *             if the next token does not match the pattern given.
      */
     public String next(String pattern) {
         return next(Pattern.compile(pattern));
     }
 
     /**
-     * Returns the next token as a BigDecimal. Will block if input is being
-     * read.
+     * Returns the next token as a {@code BigDecimal}. This method will block if input is
+     * being read. If the next token can be translated into a {@code BigDecimal}
+     * the following is done: All {@code Locale}-specific prefixes, group separators,
+     * and {@code Locale}-specific suffixes are removed. Then non-ASCII digits are
+     * mapped into ASCII digits via {@link Character#digit(char, int)}, and a
+     * negative sign (-) is added if the {@code Locale}-specific negative prefix or
+     * suffix was present. Finally the resulting string is passed to
+     * {@code BigDecimal(String) }.
      * 
-     * If the next token can be translated into a BigDecimal the following is
-     * done: All locale specific prefixes, group separators, and locale specific
-     * suffixes are removed. Then non-ASCII digits are mapped into ASCII digits
-     * via {@link Character#digit(char, int)}, a negative sign (-) is added if
-     * the locale specific negative prefix or suffix was present. Finally the
-     * resulting String is passed to {@link BigDecimal#BigDecimal(String)}}.
-     * 
-     * @return the next token as a BigDecimal
+     * @return the next token as a {@code BigDecimal}.
      * @throws IllegalStateException
-     *             if this scanner has been closed
+     *             if this {@code Scanner} has been closed.
      * @throws NoSuchElementException
-     *             if input has been exhausted
+     *             if input has been exhausted.
      * @throws InputMismatchException
      *             if the next token can not be translated into a valid
-     *             BigDecimal
+     *             {@code BigDecimal}.
      */
     public BigDecimal nextBigDecimal() {
         checkClosed();
@@ -1091,46 +1095,44 @@
     }
 
     /**
-     * Returns the next token as a BigInteger. Will block if input is being
-     * read.
-     * 
-     * Equivalent to <code>nextBigInteger(DEFAULT_RADIX)</code>
+     * Returns the next token as a {@code BigInteger}. This method will block if input is
+     * being read. Equivalent to {@code nextBigInteger(DEFAULT_RADIX)}.
      * 
-     * @return the next token as a BigInteger
+     * @return the next token as {@code BigInteger}.
      * @throws IllegalStateException
-     *             if this scanner has been closed
+     *             if this {@code Scanner} has been closed.
      * @throws NoSuchElementException
-     *             if input has been exhausted
+     *             if input has been exhausted.
      * @throws InputMismatchException
      *             if the next token can not be translated into a valid
-     *             BigInteger
+     *             {@code BigInteger}.
      */
     public BigInteger nextBigInteger() {
         return nextBigInteger(integerRadix);
     }
 
     /**
-     * Returns the next token as a BigInteger with the specified radix. Will
-     * block if input is being read.
-     * 
-     * If the next token can be translated into a BigInteger the following is
-     * done: All locale specific prefixes, group separators, and locale specific
-     * suffixes are removed. Then non-ASCII digits are mapped into ASCII digits
-     * via {@link Character#digit(char, int)}, a negative sign (-) is added if
-     * the locale specific negative prefix or suffix was present. Finally the
+     * Returns the next token as a {@code BigInteger} with the specified radix.
+     * This method will block if input is being read. If the next token can be translated
+     * into a {@code BigInteger} the following is done: All {@code Locale}-specific
+     * prefixes, group separators, and {@code Locale}-specific suffixes are removed.
+     * Then non-ASCII digits are mapped into ASCII digits via
+     * {@link Character#digit(char, int)}, and a negative sign (-) is added if the
+     * {@code Locale}-specific negative prefix or suffix was present. Finally the
      * resulting String is passed to {@link BigInteger#BigInteger(String, int)}}
      * with the specified radix.
      * 
      * @param radix
-     *            the radix used to translate the token into a BigInteger
-     * @return the next token as a BigInteger
+     *            the radix used to translate the token into a
+     *            {@code BigInteger}.
+     * @return the next token as a {@code BigInteger}
      * @throws IllegalStateException
-     *             if this scanner has been closed
+     *             if this {@code Scanner} has been closed.
      * @throws NoSuchElementException
-     *             if input has been exhausted
+     *             if input has been exhausted.
      * @throws InputMismatchException
      *             if the next token can not be translated into a valid
-     *             BigInteger
+     *             {@code BigInteger}.
      */
     public BigInteger nextBigInteger(int radix) {
         checkClosed();
@@ -1155,61 +1157,60 @@
     }
 
     /**
-     * Returns the next token as a boolean. Will block if input is being read.
+     * Returns the next token as a {@code boolean}. This method will block if input is
+     * being read.
      * 
-     * @return the next token as a boolean
+     * @return the next token as a {@code boolean}.
      * @throws IllegalStateException
-     *             if this scanner has been closed
+     *             if this {@code Scanner} has been closed.
      * @throws NoSuchElementException
-     *             if input has been exhausted
+     *             if input has been exhausted.
      * @throws InputMismatchException
-     *             if the next token can not be translated into a valid boolean
-     *             value
+     *             if the next token can not be translated into a valid
+     *             {@code boolean} value.
      */
     public boolean nextBoolean() {
         return Boolean.parseBoolean(next(BOOLEAN_PATTERN));
     }
 
     /**
-     * Returns the next token as a byte. Will block if input is being read.
-     * 
-     * Equivalent to <code>nextByte(DEFAULT_RADIX)</code>
+     * Returns the next token as a {@code byte}. This method will block if input is being
+     * read. Equivalent to {@code nextByte(DEFAULT_RADIX)}.
      * 
-     * @return the next token as a byte
+     * @return the next token as a {@code byte}.
      * @throws IllegalStateException
-     *             if this scanner has been closed
+     *             if this {@code Scanner} has been closed.
      * @throws NoSuchElementException
-     *             if input has been exhausted
+     *             if input has been exhausted.
      * @throws InputMismatchException
-     *             if the next token can not be translated into a valid byte
-     *             value
+     *             if the next token can not be translated into a valid
+     *             {@code byte} value.
      */
     public byte nextByte() {
         return nextByte(integerRadix);
     }
 
     /**
-     * Returns the next token as a byte with the specified radix. Will block if
-     * input is being read.
-     * 
-     * If the next token can be translated into a byte the following is done:
-     * All locale specific prefixes, group separators, and locale specific
-     * suffixes are removed. Then non-ASCII digits are mapped into ASCII digits
-     * via {@link Character#digit(char, int)}, a negative sign (-) is added if
-     * the locale specific negative prefix or suffix was present. Finally the
+     * Returns the next token as a {@code byte} with the specified radix. Will
+     * block if input is being read. If the next token can be translated into a
+     * {@code byte} the following is done: All {@code Locale}-specific prefixes, group
+     * separators, and {@code Locale}-specific suffixes are removed. Then non-ASCII
+     * digits are mapped into ASCII digits via
+     * {@link Character#digit(char, int)}, and a negative sign (-) is added if the
+     * {@code Locale}-specific negative prefix or suffix was present. Finally the
      * resulting String is passed to {@link Byte#parseByte(String, int)}} with
      * the specified radix.
      * 
      * @param radix
-     *            the radix used to translate the token into byte value
-     * @return the next token as a byte
+     *            the radix used to translate the token into {@code byte} value.
+     * @return the next token as a {@code byte}.
      * @throws IllegalStateException
-     *             if this scanner has been closed
+     *             if this {@code Scanner} has been closed.
      * @throws NoSuchElementException
-     *             if input has been exhausted
+     *             if input has been exhausted.
      * @throws InputMismatchException
-     *             if the next token can not be translated into a valid byte
-     *             value
+     *             if the next token can not be translated into a valid
+     *             {@code byte} value.
      */
     @SuppressWarnings("boxing")
     public byte nextByte(int radix) {
@@ -1235,25 +1236,25 @@
     }
 
     /**
-     * Returns the next token as a double. Will block if input is being read.
-     * 
-     * If the next token can be translated into a double the following is done:
-     * All locale specific prefixes, group separators, and locale specific
-     * suffixes are removed. Then non-ASCII digits are mapped into ASCII digits
-     * via {@link Character#digit(char, int)}, a negative sign (-) is added if
-     * the locale specific negative prefix or suffix was present. Finally the
-     * resulting String is passed to {@link Double#parseDouble(String)}}. If
-     * the token matches the localized NaN or infinity strings, it is also
-     * passed to {@link Double#parseDouble(String)}}.
+     * Returns the next token as a {@code double}. This method will block if input is being
+     * read. If the next token can be translated into a {@code double} the
+     * following is done: All {@code Locale}-specific prefixes, group separators, and
+     * {@code Locale}-specific suffixes are removed. Then non-ASCII digits are mapped
+     * into ASCII digits via {@link Character#digit(char, int)}, and a negative
+     * sign (-) is added if the {@code Locale}-specific negative prefix or suffix was
+     * present. Finally the resulting String is passed to
+     * {@link Double#parseDouble(String)}}. If the token matches the localized
+     * NaN or infinity strings, it is also passed to
+     * {@link Double#parseDouble(String)}}.
      * 
-     * @return the next token as a double
+     * @return the next token as a {@code double}.
      * @throws IllegalStateException
-     *             if this scanner has been closed
+     *             if this {@code Scanner} has been closed.
      * @throws NoSuchElementException
-     *             if input has been exhausted
+     *             if input has been exhausted.
      * @throws InputMismatchException
-     *             if the next token can not be translated into a valid double
-     *             value
+     *             if the next token can not be translated into a valid
+     *             {@code double} value.
      */
     @SuppressWarnings("boxing")
     public double nextDouble() {
@@ -1279,25 +1280,25 @@
     }
 
     /**
-     * Returns the next token as a float. Will block if input is being read.
-     * 
-     * If the next token can be translated into a float the following is done:
-     * All locale specific prefixes, group separators, and locale specific
-     * suffixes are removed. Then non-ASCII digits are mapped into ASCII digits
-     * via {@link Character#digit(char, int)}, a negative sign (-) is added if
-     * the locale specific negative prefix or suffix was present. Finally the
-     * resulting String is passed to {@link Float#parseFloat(String)}}.If the
-     * token matches the localized NaN or infinity strings, it is also passed to
+     * Returns the next token as a {@code float}. This method will block if input is being
+     * read. If the next token can be translated into a {@code float} the
+     * following is done: All {@code Locale}-specific prefixes, group separators, and
+     * {@code Locale}-specific suffixes are removed. Then non-ASCII digits are mapped
+     * into ASCII digits via {@link Character#digit(char, int)}, and a negative
+     * sign (-) is added if the {@code Locale}-specific negative prefix or suffix was
+     * present. Finally the resulting String is passed to
+     * {@link Float#parseFloat(String)}}.If the token matches the localized NaN
+     * or infinity strings, it is also passed to
      * {@link Float#parseFloat(String)}}.
      * 
-     * @return the next token as a float
+     * @return the next token as a {@code float}.
      * @throws IllegalStateException
-     *             if this scanner has been closed
+     *             if this {@code Scanner} has been closed.
      * @throws NoSuchElementException
-     *             if input has been exhausted
+     *             if input has been exhausted.
      * @throws InputMismatchException
-     *             if the next token can not be translated into a valid float
-     *             value
+     *             if the next token can not be translated into a valid
+     *             {@code float} value.
      */
     @SuppressWarnings("boxing")
     public float nextFloat() {
@@ -1323,45 +1324,44 @@
     }
 
     /**
-     * Returns the next token as an int. Will block if input is being read.
+     * Returns the next token as an {@code int}. This method will block if input is being
+     * read. Equivalent to {@code nextInt(DEFAULT_RADIX)}.
      * 
-     * Equivalent to <code>nextInt(DEFAULT_RADIX)</code>.
-     * 
-     * @return the next token as an int
+     * @return the next token as an {@code int}
      * @throws IllegalStateException
-     *             if this scanner has been closed
+     *             if this {@code Scanner} has been closed.
      * @throws NoSuchElementException
-     *             if input has been exhausted
+     *             if input has been exhausted.
      * @throws InputMismatchException
-     *             if the next token can not be translated into a valid int
-     *             value
+     *             if the next token can not be translated into a valid
+     *             {@code int} value.
      */
     public int nextInt() {
         return nextInt(integerRadix);
     }
 
     /**
-     * Returns the next token as an int with the specified radix. Will block if
-     * input is being read.
-     * 
-     * If the next token can be translated into an int the following is done:
-     * All locale specific prefixes, group separators, and locale specific
-     * suffixes are removed. Then non-ASCII digits are mapped into ASCII digits
-     * via {@link Character#digit(char, int)}, a negative sign (-) is added if
-     * the locale specific negative prefix or suffix was present. Finally the
+     * Returns the next token as an {@code int} with the specified radix. This method will
+     * block if input is being read. If the next token can be translated into an
+     * {@code int} the following is done: All {@code Locale}-specific prefixes, group
+     * separators, and {@code Locale}-specific suffixes are removed. Then non-ASCII
+     * digits are mapped into ASCII digits via
+     * {@link Character#digit(char, int)}, and a negative sign (-) is added if the
+     * {@code Locale}-specific negative prefix or suffix was present. Finally the
      * resulting String is passed to {@link Integer#parseInt(String, int)} with
      * the specified radix.
      * 
      * @param radix
-     *            the radix used to translate the token into an int value
-     * @return the next token as an int
+     *            the radix used to translate the token into an {@code int}
+     *            value.
+     * @return the next token as an {@code int}.
      * @throws IllegalStateException
-     *             if this scanner has been closed
+     *             if this {@code Scanner} has been closed.
      * @throws NoSuchElementException
-     *             if input has been exhausted
+     *             if input has been exhausted.
      * @throws InputMismatchException
-     *             if the next token can not be translated into a valid int
-     *             value
+     *             if the next token can not be translated into a valid
+     *             {@code int} value.
      */
     @SuppressWarnings("boxing")
     public int nextInt(int radix) {
@@ -1387,18 +1387,17 @@
     }
 
     /**
-     * Returns the skipped input and advances the scanner to the beginning of
-     * the next line. The returned result will exclude any line terminator.
-     * 
-     * When searching, if no line terminator is found, then a large amount of
-     * input will be cached. If no line at all can be found, a
-     * NoSuchElementException will be thrown out.
+     * Returns the skipped input and advances the {@code Scanner} to the beginning of
+     * the next line. The returned result will exclude any line terminator. When
+     * searching, if no line terminator is found, then a large amount of input
+     * will be cached. If no line at all can be found, a {@code NoSuchElementException}
+     * will be thrown.
      * 
-     * @return the skipped line
+     * @return the skipped line.
      * @throws IllegalStateException
-     *             if the scanner is closed
+     *             if the {@code Scanner} is closed.
      * @throws NoSuchElementException
-     *             if no line can be found, e.g. when input is an empty string
+     *             if no line can be found, e.g. when input is an empty string.
      */
     public String nextLine() {
         checkClosed();
@@ -1437,45 +1436,44 @@
     }
 
     /**
-     * Returns the next token as a long. Will block if input is being read.
+     * Returns the next token as a {@code long}. This method will block if input is being
+     * read. Equivalent to {@code nextLong(DEFAULT_RADIX)}.
      * 
-     * Equivalent to <code>nextLong(DEFAULT_RADIX)</code>.
-     * 
-     * @return the next token as a long
+     * @return the next token as a {@code long}.
      * @throws IllegalStateException
-     *             if this scanner has been closed
+     *             if this {@code Scanner} has been closed.
      * @throws NoSuchElementException
-     *             if input has been exhausted
+     *             if input has been exhausted.
      * @throws InputMismatchException
-     *             if the next token can not be translated into a valid long
-     *             value
+     *             if the next token can not be translated into a valid
+     *             {@code long} value.
      */
     public long nextLong() {
         return nextLong(integerRadix);
     }
 
     /**
-     * Returns the next token as a long with the specified radix. Will block if
-     * input is being read.
-     * 
-     * If the next token can be translated into a long the following is done:
-     * All locale specific prefixes, group separators, and locale specific
-     * suffixes are removed. Then non-ASCII digits are mapped into ASCII digits
-     * via {@link Character#digit(char, int)}, a negative sign (-) is added if
-     * the locale specific negative prefix or suffix was present. Finally the
+     * Returns the next token as a {@code long} with the specified radix. This method will
+     * block if input is being read. If the next token can be translated into a
+     * {@code long} the following is done: All {@code Locale}-specific prefixes, group
+     * separators, and {@code Locale}-specific suffixes are removed. Then non-ASCII
+     * digits are mapped into ASCII digits via
+     * {@link Character#digit(char, int)}, and a negative sign (-) is added if the
+     * {@code Locale}-specific negative prefix or suffix was present. Finally the
      * resulting String is passed to {@link Long#parseLong(String, int)}} with
      * the specified radix.
      * 
      * @param radix
-     *            the radix used to translate the token into a long value
-     * @return the long value scanned from the input
+     *            the radix used to translate the token into a {@code long}
+     *            value.
+     * @return the next token as a {@code long}.
      * @throws IllegalStateException
-     *             if this scanner has been closed
+     *             if this {@code Scanner} has been closed.
      * @throws NoSuchElementException
-     *             if input has been exhausted
+     *             if input has been exhausted.
      * @throws InputMismatchException
-     *             if the next token can not be translated into a valid long
-     *             value
+     *             if the next token can not be translated into a valid
+     *             {@code long} value.
      */
     @SuppressWarnings("boxing")
     public long nextLong(int radix) {
@@ -1501,45 +1499,44 @@
     }
 
     /**
-     * Returns the next token as a short. Will block if input is being read.
-     * 
-     * Equivalent to <code>nextShort(DEFAULT_RADIX)</code>.
+     * Returns the next token as a {@code short}. This method will block if input is being
+     * read. Equivalent to {@code nextShort(DEFAULT_RADIX)}.
      * 
-     * @return the next token as a short
+     * @return the next token as a {@code short}.
      * @throws IllegalStateException
-     *             if this scanner has been closed
+     *             if this {@code Scanner} has been closed.
      * @throws NoSuchElementException
-     *             if input has been exhausted
+     *             if input has been exhausted.
      * @throws InputMismatchException
-     *             if the next token can not be translated into a valid short
-     *             value
+     *             if the next token can not be translated into a valid
+     *             {@code short} value.
      */
     public short nextShort() {
         return nextShort(integerRadix);
     }
 
     /**
-     * Returns the next token as a short with the specified radix. Will block if
-     * input is being read.
-     * 
-     * If the next token can be translated into a short the following is done:
-     * All locale specific prefixes, group separators, and locale specific
-     * suffixes are removed. Then non-ASCII digits are mapped into ASCII digits
-     * via {@link Character#digit(char, int)}, a negative sign (-) is added if
-     * the locale specific negative prefix or suffix was present. Finally the
+     * Returns the next token as a {@code short} with the specified radix. This method will
+     * block if input is being read. If the next token can be translated into a
+     * {@code short} the following is done: All {@code Locale}-specific prefixes, group
+     * separators, and {@code Locale}-specific suffixes are removed. Then non-ASCII
+     * digits are mapped into ASCII digits via
+     * {@link Character#digit(char, int)}, and a negative sign (-) is added if the
+     * {@code Locale}-specific negative prefix or suffix was present. Finally the
      * resulting String is passed to {@link Short#parseShort(String, int)}}
      * with the specified radix.
      * 
      * @param radix
-     *            the radix used to translate the token into short value
-     * @return the short value scanned from the input
+     *            the radix used to translate the token into {@code short}
+     *            value.
+     * @return the next token as a {@code short}.
      * @throws IllegalStateException
-     *             if this scanner has been closed
+     *             if this {@code Scanner} has been closed.
      * @throws NoSuchElementException
-     *             if input has been exhausted
+     *             if input has been exhausted.
      * @throws InputMismatchException
-     *             if the next token can not be translated into a valid short
-     *             value
+     *             if the next token can not be translated into a valid
+     *             {@code short} value.
      */
     @SuppressWarnings("boxing")
     public short nextShort(int radix) {
@@ -1565,34 +1562,29 @@
     }
 
     /**
-     * Return the radix of this scanner.
+     * Return the radix of this {@code Scanner}.
      * 
-     * @return the radix of this scanner
+     * @return the radix of this {@code Scanner}
      */
     public int radix() {
         return integerRadix;
     }
 
     /**
-     * Tries to use specified pattern to match input from the current position.
-     * The delimiter will be ignored. If matches, the matched input will be
-     * skipped. If an anchored match of the specified pattern succeeds, input
-     * will also be skipped. Otherwise, a NoSuchElementException will be thrown
-     * out.
-     * 
-     * Patterns that can match a lot of input may cause the scanner to read in a
-     * large amount of input.
-     * 
-     * Uses a pattern that matches nothing( sc.skip(Pattern.compile("[ \t]*")) )
-     * will suppress NoSuchElementException.
+     * Tries to use specified pattern to match input starting from the current position.
+     * The delimiter will be ignored. If a match is found, the matched input will be
+     * skipped. If an anchored match of the specified pattern succeeds, the corresponding input
+     * will also be skipped. Otherwise, a {@code NoSuchElementException} will be thrown.
+     * Patterns that can match a lot of input may cause the {@code Scanner} to read
+     * in a large amount of input.
      * 
      * @param pattern
-     *            used to skip over input
-     * @return the scanner itself
+     *            used to skip over input.
+     * @return the {@code Scanner} itself.
      * @throws IllegalStateException
-     *             if the scanner is closed
+     *             if the {@code Scanner} is closed.
      * @throws NoSuchElementException
-     *             if the specified pattern match fails
+     *             if the specified pattern match fails.
      */
     public Scanner skip(Pattern pattern) {
         checkClosed();
@@ -1623,29 +1615,27 @@
     }
 
     /**
-     * Tries to use the specified string to construct a pattern. And then uses
-     * the constructed pattern to match input from the current position. The
-     * delimiter will be ignored.
-     * 
-     * It is the same as invoke skip(Pattern.compile(pattern))
+     * Tries to use the specified string to construct a pattern and then uses
+     * the constructed pattern to match input starting from the current position. The
+     * delimiter will be ignored. This call is the same as invoke
+     * {@code skip(Pattern.compile(pattern))}.
      * 
      * @param pattern
-     *            the string used to construct a pattern which in turn used to
-     *            match input
-     * @return the matched input
+     *            the string used to construct a pattern which in turn is used to
+     *            match input.
+     * @return the {@code Scanner} itself.
      * @throws IllegalStateException
-     *             if the scanner is closed
+     *             if the {@code Scanner} is closed.
      */
     public Scanner skip(String pattern) {
         return skip(Pattern.compile(pattern));
     }
 
     /**
-     * Returns a string. The string is used to represent this scanner. Contained
-     * information may be helpful for debugging. The format of the string is
-     * unspecified.
+     * Returns a string representation of this {@code Scanner}. The information
+     * returned may be helpful for debugging. The format of the string is unspecified.
      * 
-     * @return a string to represent this scanner
+     * @return a string represendation of this {@code Scanner}.
      */
     @Override
     public String toString() {
@@ -1660,11 +1650,11 @@
     }
 
     /**
-     * Set the delimiting pattern of this scanner
+     * Sets the delimiting pattern of this {@code Scanner}.
      * 
      * @param pattern
-     *            the delimiting pattern to use
-     * @return this scanner
+     *            the delimiting pattern to use.
+     * @return this {@code Scanner}.
      */
     public Scanner useDelimiter(Pattern pattern) {
         delimiter = pattern;
@@ -1672,24 +1662,23 @@
     }
 
     /**
-     * Set the delimiting pattern of this scanner with a pattern compiled from
-     * the supplied string value
+     * Sets the delimiting pattern of this {@code Scanner} with a pattern compiled from
+     * the supplied string value.
      * 
      * @param pattern
-     *            a string from which a <code>Pattern</code> can be compiled
-     * @return this scanner
+     *            a string from which a {@code Pattern} can be compiled.
+     * @return this {@code Scanner}.
      */
     public Scanner useDelimiter(String pattern) {
         return useDelimiter(Pattern.compile(pattern));
     }
 
     /**
-     * 
-     * Set the locale of this scanner to a specified locale.
-     * 
+     * Sets the {@code Locale} of this {@code Scanner} to a specified {@code Locale}.
+     *
      * @param l
-     *            the specified locale to use
-     * @return this scanner
+     *            the specified {@code Locale} to use.
+     * @return this {@code Scanner}.
      */
     public Scanner useLocale(Locale l) {
         if (null == l) {
@@ -1700,12 +1689,11 @@
     }
 
     /**
-     * 
-     * Set the radix of this scanner to the specified radix.
-     * 
+     * Sets the radix of this {@code Scanner} to the specified radix.
+     *
      * @param radix
-     *            the specified radix to use
-     * @return this scanner
+     *            the specified radix to use.
+     * @return this {@code Scanner}.
      */
     public Scanner useRadix(int radix) {
         if (radix < Character.MIN_RADIX || radix > Character.MAX_RADIX) {
@@ -1717,9 +1705,10 @@
     }
 
     /**
-     * Remove is not a supported operation on Scanner.
+     * Remove is not a supported operation on {@code Scanner}.
      * 
-     * @throws UnsupportedOperationException if this method is invoked
+     * @throws UnsupportedOperationException
+     *             if this method is invoked.
      */
     public void remove() {
         throw new UnsupportedOperationException();
@@ -1735,7 +1724,7 @@
     }
 
     /*
-     * Check the scanner's state, if it is closed, IllegalStateException will be
+     * Check the {@code Scanner}'s state, if it is closed, IllegalStateException will be
      * thrown.
      */
     private void checkClosed() {
@@ -1745,8 +1734,8 @@
     }
 
     /*
-     * Check the given pattern. If it is null, then a NullPointerException will
-     * be thrown.
+     * Check the inputed pattern. If it is null, then a NullPointerException
+     * will be thrown out.
      */
     private void checkNull(Pattern pattern) {
         if (null == pattern) {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Set.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Set.java?rev=772785&r1=772784&r2=772785&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Set.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/util/Set.java Thu May  7 21:43:41 2009
@@ -17,182 +17,180 @@
 
 package java.util;
 
+
 /**
- * Set is a collection which does not allow duplicate elements.
- * 
+ * A {@code Set} is a data structure which does not allow duplicate elements.
+ *
  * @since 1.2
  */
 public interface Set<E> extends Collection<E> {
-
+    
     /**
-     * Adds the specified object to this Set. The Set is not modified if it
+     * Adds the specified object to this set. The set is not modified if it
      * already contains the object.
      * 
      * @param object
-     *            the object to add
-     * @return true if this Set is modified, false otherwise
-     * 
-     * @exception UnsupportedOperationException
-     *                when adding to this Set is not supported
-     * @exception ClassCastException
-     *                when the class of the object is inappropriate for this Set
-     * @exception IllegalArgumentException
-     *                when the object cannot be added to this Set
+     *            the object to add.
+     * @return {@code true} if this set is modified, {@code false} otherwise.
+     * @throws UnsupportedOperationException
+     *             when adding to this set is not supported.
+     * @throws ClassCastException
+     *             when the class of the object is inappropriate for this set.
+     * @throws IllegalArgumentException
+     *             when the object cannot be added to this set.
      */
     public boolean add(E object);
 
     /**
-     * Adds the objects in the specified Collection which do not exist in this
-     * Set.
+     * Adds the objects in the specified collection which do not exist yet in
+     * this set.
      * 
      * @param collection
-     *            the Collection of objects
-     * @return true if this Set is modified, false otherwise
-     * 
-     * @exception UnsupportedOperationException
-     *                when adding to this Set is not supported
-     * @exception ClassCastException
-     *                when the class of an object is inappropriate for this Set
-     * @exception IllegalArgumentException
-     *                when an object cannot be added to this Set
+     *            the collection of objects.
+     * @return {@code true} if this set is modified, {@code false} otherwise.
+     * @throws UnsupportedOperationException
+     *             when adding to this set is not supported.
+     * @throws ClassCastException
+     *             when the class of an object is inappropriate for this set.
+     * @throws IllegalArgumentException
+     *             when an object cannot be added to this set.
      */
     public boolean addAll(Collection<? extends E> collection);
 
     /**
-     * Removes all elements from this Set, leaving it empty.
-     * 
-     * @exception UnsupportedOperationException
-     *                when removing from this Set is not supported
+     * Removes all elements from this set, leaving it empty.
      * 
+     * @throws UnsupportedOperationException
+     *             when removing from this set is not supported.
      * @see #isEmpty
      * @see #size
      */
     public void clear();
 
     /**
-     * Searches this Set for the specified object.
+     * Searches this set for the specified object.
      * 
      * @param object
-     *            the object to search for
-     * @return true if object is an element of this Set, false otherwise
+     *            the object to search for.
+     * @return {@code true} if object is an element of this set, {@code false}
+     *         otherwise.
      */
     public boolean contains(Object object);
 
     /**
-     * Searches this Set for all objects in the specified Collection.
+     * Searches this set for all objects in the specified collection.
      * 
      * @param collection
-     *            the Collection of objects
-     * @return true if all objects in the specified Collection are elements of
-     *         this Set, false otherwise
+     *            the collection of objects.
+     * @return {@code true} if all objects in the specified collection are
+     *         elements of this set, {@code false} otherwise.
      */
     public boolean containsAll(Collection<?> collection);
 
     /**
-     * Compares the argument to the receiver, and answers true if they represent
-     * the <em>same</em> object using a class specific comparison.
+     * Compares the specified object to this set, and returns true if they
+     * represent the <em>same</em> object using a class specific comparison.
+     * Equality for a set means that both sets have the same size and the same
+     * elements.
      * 
      * @param object
-     *            Object the object to compare with this object.
-     * @return boolean <code>true</code> if the object is the same as this
-     *         object <code>false</code> if it is different from this object.
+     *            the object to compare with this object.
+     * @return boolean {@code true} if the object is the same as this object,
+     *         and {@code false} if it is different from this object.
      * @see #hashCode
      */
     public boolean equals(Object object);
 
     /**
-     * Answers an integer hash code for the receiver. Objects which are equal
-     * answer the same value for this method.
+     * Returns the hash code for this set. Two set which are equal must return
+     * the same value.
      * 
-     * @return the receiver's hash
+     * @return the hash code of this set.
      * 
      * @see #equals
      */
     public int hashCode();
 
     /**
-     * Answers if this Set has no elements, a size of zero.
-     * 
-     * @return true if this Set has no elements, false otherwise
+     * Returns true if this set has no elements.
      * 
+     * @return {@code true} if this set has no elements, {@code false}
+     *         otherwise.
      * @see #size
      */
     public boolean isEmpty();
 
     /**
-     * Answers an Iterator on the elements of this Set.
-     * 
-     * @return an Iterator on the elements of this Set
+     * Returns an iterator on the elements of this set. The elements are
+     * unordered.
      * 
+     * @return an iterator on the elements of this set.
      * @see Iterator
      */
     public Iterator<E> iterator();
 
     /**
-     * Removes any occurrence of the specified object from this Set.
+     * Removes the specified object from this set.
      * 
      * @param object
-     *            the object to remove
-     * @return true if this Set is modified, false otherwise
-     * 
-     * @exception UnsupportedOperationException
-     *                when removing from this Set is not supported
+     *            the object to remove.
+     * @return {@code true} if this set was modified, {@code false} otherwise.
+     * @throws UnsupportedOperationException
+     *             when removing from this set is not supported.
      */
     public boolean remove(Object object);
 
     /**
-     * Removes all objects in the specified Collection from this Set.
+     * Removes all objects in the specified collection from this set.
      * 
      * @param collection
-     *            the Collection of objects to remove
-     * @return true if this Set is modified, false otherwise
-     * 
-     * @exception UnsupportedOperationException
-     *                when removing from this Set is not supported
+     *            the collection of objects to remove.
+     * @return {@code true} if this set was modified, {@code false} otherwise.
+     * @throws UnsupportedOperationException
+     *             when removing from this set is not supported.
      */
     public boolean removeAll(Collection<?> collection);
 
     /**
-     * Removes all objects from this Set that are not contained in the specified
-     * Collection.
+     * Removes all objects from this set that are not contained in the specified
+     * collection.
      * 
      * @param collection
-     *            the Collection of objects to retain
-     * @return true if this Set is modified, false otherwise
-     * 
-     * @exception UnsupportedOperationException
-     *                when removing from this Set is not supported
+     *            the collection of objects to retain.
+     * @return {@code true} if this set was modified, {@code false} otherwise.
+     * @throws UnsupportedOperationException
+     *             when removing from this set is not supported.
      */
     public boolean retainAll(Collection<?> collection);
 
     /**
-     * Answers the number of elements in this Set.
+     * Returns the number of elements in this set.
      * 
-     * @return the number of elements in this Set
+     * @return the number of elements in this set.
      */
     public int size();
 
     /**
-     * Answers an array containing all elements contained in this Set.
+     * Returns an array containing all elements contained in this set.
      * 
-     * @return an array of the elements from this Set
+     * @return an array of the elements from this set.
      */
     public Object[] toArray();
 
     /**
-     * Answers an array containing all elements contained in this Set. If the
+     * Returns an array containing all elements contained in this set. If the
      * specified array is large enough to hold the elements, the specified array
      * is used, otherwise an array of the same type is created. If the specified
-     * array is used and is larger than this Set, the array element following
+     * array is used and is larger than this set, the array element following
      * the collection elements is set to null.
      * 
      * @param array
-     *            the array
-     * @return an array of the elements from this Set
-     * 
-     * @exception ArrayStoreException
-     *                when the type of an element in this Set cannot be stored
-     *                in the type of the specified array
+     *            the array.
+     * @return an array of the elements from this set.
+     * @throws ArrayStoreException
+     *             when the type of an element in this set cannot be stored in
+     *             the type of the specified array.
+     * @see Collection#toArray(Object[])
      */
     public <T> T[] toArray(T[] array);
 }



Mime
View raw message