Merge

src/java.base/share/classes/java/lang/String.java

@@ -2764,30 +2764,32 @@ public final class String
     }
 
     /**
-     * Returns a stream of substrings extracted from this string
-     * partitioned by line terminators.
+     * Returns a stream of lines extracted from this string,
+     * separated by line terminators.
      * <p>
-     * Line terminators recognized are line feed
-     * {@code "\n"} ({@code U+000A}),
-     * carriage return
-     * {@code "\r"} ({@code U+000D})
-     * and a carriage return followed immediately by a line feed
-     * {@code "\r\n"} ({@code U+000D U+000A}).
+     * A <i>line terminator</i> is one of the following:
+     * a line feed character {@code "\n"} (U+000A),
+     * a carriage return character {@code "\r"} (U+000D),
+     * or a carriage return followed immediately by a line feed
+     * {@code "\r\n"} (U+000D U+000A).
      * <p>
-     * The stream returned by this method contains each line of
-     * this string that is terminated by a line terminator except that
-     * the last line can either be terminated by a line terminator or the
-     * end of the string.
-     * The lines in the stream are in the order in which
-     * they occur in this string and do not include the line terminators
-     * partitioning the lines.
+     * A <i>line</i> is either a sequence of zero or more characters
+     * followed by a line terminator, or it is a sequence of one or
+     * more characters followed by the end of the string. A
+     * line does not include the line terminator.
+     * <p>
+     * The stream returned by this method contains the lines from
+     * this string in the order in which they occur.
+     *
+     * @apiNote This definition of <i>line</i> implies that an empty
+     *          string has zero lines and that there is no empty line
+     *          following a line terminator at the end of a string.
      *
      * @implNote This method provides better performance than
      *           split("\R") by supplying elements lazily and
      *           by faster search of new line terminators.
      *
-     * @return  the stream of strings extracted from this string
-     *          partitioned by line terminators
+     * @return  the stream of lines extracted from this string
      *
      * @since 11
      */

src/java.base/share/classes/java/security/Signature.java

@@ -700,7 +700,7 @@ public abstract class Signature extends SignatureSpi {
      * encoded or of the wrong type, if this signature algorithm is unable to
      * process the input data provided, etc.
      * @exception IllegalArgumentException if the {@code signature}
-     * byte array is null, or the {@code offset} or {@code length}
+     * byte array is {@code null}, or the {@code offset} or {@code length}
      * is less than 0, or the sum of the {@code offset} and
      * {@code length} is greater than the length of the
      * {@code signature} byte array.
@@ -897,14 +897,15 @@ public abstract class Signature extends SignatureSpi {
     /**
      * Returns the parameters used with this signature object.
      *
-     * <p>The returned parameters may be the same that were used to initialize
-     * this signature, or may contain a combination of default and randomly
-     * generated parameter values used by the underlying signature
-     * implementation if this signature requires algorithm parameters but
-     * was not initialized with any.
+     * <p> If this signature has been previously initialized with parameters
+     * (by calling the {@code setParameter} method), this method returns
+     * the same parameters. If this signature has not been initialized with
+     * parameters, this method may return a combination of default and
+     * randomly generated parameter values if the underlying
+     * signature implementation supports it and can successfully generate
+     * them. Otherwise, {@code null} is returned.
      *
-     * @return the parameters used with this signature, or null if this
-     * signature does not use any parameters.
+     * @return the parameters used with this signature, or {@code null}
      *
      * @see #setParameter(AlgorithmParameterSpec)
      * @since 1.4
@@ -925,7 +926,7 @@ public abstract class Signature extends SignatureSpi {
      *
      * @param param the string name of the parameter.
      *
-     * @return the object that represents the parameter value, or null if
+     * @return the object that represents the parameter value, or {@code null} if
      * there is none.
      *
      * @exception InvalidParameterException if {@code param} is an invalid

src/java.base/share/classes/java/security/SignatureSpi.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2018, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -326,18 +326,18 @@ public abstract class SignatureSpi {
     }
 
     /**
-     * <p>This method is overridden by providers to return the
-     * parameters used with this signature engine, or null
-     * if this signature engine does not use any parameters.
+     * <p>This method is overridden by providers to return the parameters
+     * used with this signature engine.
      *
-     * <p>The returned parameters may be the same that were used to initialize
-     * this signature engine, or may contain a combination of default and
-     * randomly generated parameter values used by the underlying signature
-     * implementation if this signature engine requires algorithm parameters
-     * but was not initialized with any.
+     * <p> If this signature engine has been previously initialized with
+     * parameters (by calling the {@code engineSetParameter} method), this
+     * method returns the same parameters. If this signature engine has not been
+     * initialized with parameters, this method may return a combination of
+     * default and randomly generated parameter values if the underlying
+     * signature implementation supports it and can successfully generate
+     * them. Otherwise, {@code null} is returned.
      *
-     * @return the parameters used with this signature engine, or null if this
-     * signature engine does not use any parameters
+     * @return the parameters used with this signature engine, or {@code null}
      *
      * @exception UnsupportedOperationException if this method is
      * not overridden by a provider
@@ -360,7 +360,7 @@ public abstract class SignatureSpi {
      *
      * @param param the string name of the parameter.
      *
-     * @return the object that represents the parameter value, or null if
+     * @return the object that represents the parameter value, or {@code null} if
      * there is none.
      *
      * @exception InvalidParameterException if {@code param} is an