JDK 9 doc-only RFR of 8180353: FileOutputStream documentation does not indicate properly whether files get truncated or not

[Brian Burkhalter]

Hi Chris,

Let’s skip the first revision (May 16, 2017, at 12:54 PM PDT) of the patch and go for this one instead:

--- a/src/java.base/share/classes/java/io/FileOutputStream.java
+++ b/src/java.base/share/classes/java/io/FileOutputStream.java
@@ -91,6 +91,10 @@
      * If the file exists but is a directory rather than a regular file, does
      * not exist but cannot be created, or cannot be opened for any other
      * reason then a <code>FileNotFoundException</code> is thrown.
+     * <p>
+     * @implSpec Invoking this constructor with the parameter {@code name} is
+     * equivalent to invoking {@link #FileOutputStream(String,boolean)
+     * new FileOutputStream(name, false)}.
      *
      * @param      name   the system-dependent filename
      * @exception  FileNotFoundException  if the file exists but is a directory

Thanks,

Brian

On May 16, 2017, at 12:54 PM, Brian Burkhalter <brian.burkhalter at oracle.com> wrote:

> Hi Chris,
> 
> Thanks for the review. Here is a revised version, thanks to a comment from Daniel, which I think might be better:
> 
> Thanks,
> 
> Brian
> 
> --- a/src/java.base/share/classes/java/io/FileOutputStream.java
> +++ b/src/java.base/share/classes/java/io/FileOutputStream.java
> @@ -91,6 +91,10 @@
>      * If the file exists but is a directory rather than a regular file, does
>      * not exist but cannot be created, or cannot be opened for any other
>      * reason then a <code>FileNotFoundException</code> is thrown.
> +     * <p>
> +     * Invoking this constructor with the parameter {@code name} is equivalent
> +     * to invoking {@link #FileOutputStream(String,boolean)
> +     * new FileOutputStream(name, false)}.
>      *
>      * @param      name   the system-dependent filename
>      * @exception  FileNotFoundException  if the file exists but is a directory
> 
> On May 16, 2017, at 1:05 AM, Chris Hegarty <chris.hegarty at oracle.com> wrote:
> 
>> Looks good Brian.
>> 
>> -Chris.
>> 
>>> On 16 May 2017, at 02:27, Brian Burkhalter <brian.burkhalter at oracle.com> wrote:
>>> 
>>> Please review at your convenience.
>>> 
>>> Issue:	https://bugs.openjdk.java.net/browse/JDK-8180353
>>> Patch:	[1]
>>> 
>>> Thanks,
>>> 
>>> Brian
>>> 
>>> [1] Hg diff
>>> 
>>> --- a/src/java.base/share/classes/java/io/FileOutputStream.java
>>> +++ b/src/java.base/share/classes/java/io/FileOutputStream.java
>>> @@ -91,6 +91,12 @@
>>>    * If the file exists but is a directory rather than a regular file, does
>>>    * not exist but cannot be created, or cannot be opened for any other
>>>    * reason then a <code>FileNotFoundException</code> is thrown.
>>> +     * <p>
>>> +     * Invoking this constructor with the parameter {@code name} is equivalent
>>> +     * to invoking the constructor {@link #FileOutputStream(String,boolean)
>>> +     * FileOutputStream(name,append)} with the same {@code String} parameter
>>> +     * {@code name} and the {@code boolean} parameter {@code append} equal to
>>> +     * {@code false}.
>>>    *
>>>    * @param      name   the system-dependent filename
>>>    * @exception  FileNotFoundException  if the file exists but is a directory
>> 
>