Documentation for -source option in javac man pages is wrong in JDK 7 and 8

[Jim Holmlund]

On 11/16/2011 1:21 PM, raymond gallardo wrote:
> Hi Jim,
>
> For *-target*, could you tell me what the correct values or (or at least make an assumption):
>
> *-target* /version/
>     Generate class files that target a specified version of the VM. Class files will run on the
>     specified target and on later versions, but not on earlier versions of the VM. Valid targets
>     are *1.1*, *1.2*, *1.3*, *1.4*, *1.5* (also *5*), *1.6* (also *6*), *1.7* (also *7*), and
>     *1.8* (also *8*).
>
>     The default for *-target* depends on the value of *-source*:
>
>         * If -source is *not specified*, the value of -target is *1.8*
>         * If -source is *1.2*, the value of -target is *1.4*
>         * If -source is *1.3*, the value of -target is *1.4*
>         * If -source is *1.5*, the value of -target is *1.7*
>         * If -source is *1.6*, the value of -target is *1.7*
>         * *If -source is 1.7, the value of -target is ???
>           *
>         * For *all other values* of -source, the value of *-target* is the value of *-source*.
>
> So if *-source* is *1.5*, *1.6*, or *1.7*, is it safe to assume that the value of *-target* would 
> be *1.8*?
>
Yes, that is correct at least as of now.  I'm not sure that it will end up being correct when JDK 8 
is released.  The current algorithm is
       if generics are not allowed (ie, source is < 1.5), then
               the default target is 1.4.
       else,
               the default target is the newest JDK.

So there was something special about generics introduced in 1.5.  Will there be something special in 
JDK 8 that will mean that the default target for 1.5, 1.6, and 1.7 should remain as 1.7?  I don't know.
- jjh

> Thanks,
> Raymond
>
> On 16/11/2011 2:49 PM, Jim Holmlund wrote:
>> Ok, thanks Raymond. Yes, I presume that the default for JDK 8 will be 1.8.
>> - jjh
>>
>> On 11/16/2011 10:48 AM, raymond gallardo wrote:
>>> Hi Jim,
>>>
>>> This is from the http://closedjdk.us.oracle.com/jdk7u/jdk7u-dev/pubs/ repository:
>>>
>>> http://writersblock.us.oracle.com:8888/jdk/pubs/docs/technotes/tools/windows/javac.html
>>> http://writersblock.us.oracle.com:8888/jdk/pubs/docs/technotes/tools/solaris/javac.html
>>>
>>> *-source* /release/
>>>     Specifies the version of source code accepted. The following values for /release/ are allowed:
>>>
>>>     *1.3*
>>>         The compiler does /not/ support assertions, generics, or other language features
>>>         introduced after Java SE 1.3.
>>>     *1.4*
>>>         The compiler accepts code containing assertions, which were introduced in Java SE 1.4.
>>>     *1.5*
>>>         The compiler accepts code containing generics and other language features introduced in
>>>         Java SE 5.
>>>     *5*
>>>         Synonym for 1.5.
>>>     *1.6*
>>>         No language changes were introduced in Java SE 6. However, encoding errors in source
>>>         files are now reported as errors instead of warnings as in previous releases of Java SE.
>>>     *6*
>>>         Synonym for 1.6.
>>>     *1.7*
>>>         This is the default value. The compiler accepts code with features introduced in Java SE 7.
>>>     *7*
>>>         Synonym for 1.7.
>>>
>>> It appears that I've made the change for the *-source */*release* /option for both Solaris and 
>>> Windows in the latest 7u documentation.
>>>
>>> However, I'll make the change to the jdk8 docs regarding the default (I'm assuming it's 1.8 ?)
>>>
>>> FYI: The Windows and Solaris versions of the javac.html file are different. The Linux version is 
>>> the same as the Solaris one.
>>>
>>> Thanks for raising this issue,
>>> Raymond
>>>
>>> On 16/11/2011 12:46 PM, Jim Holmlund wrote:
>>>> Raymond, Nico points out that this doc:
>>>> http://download.oracle.com/javase/7/docs/technotes/tools/windows/javac.html
>>>> says that 1.6 is the default for -source.
>>>>
>>>> Did you happen to fix this when you fixed 7085370?
>>>>
>>>> - jjh
>>>>
>>>> On 11/15/2011 5:29 PM, Nico R. wrote:
>>>>> Hello,
>>>>>
>>>>> in JDK 7, the man Linux/Solaris page for javac
>>>>> (jdk7/jdk/src/linux/doc/man/javac.1 and
>>>>> jdk7/jdk/src/solaris/doc/sun/man/man1/javac.1) says that 1.6 is the
>>>>> default value for -source. However, compiling a simple test program
>>>>> which uses features from version 7 works fine. If I use ‘-source 1.6’ or
>>>>> ‘-source 6’, it fails. With ‘-source 7’, it works again.
>>>>>
>>>>> These facts and the value of ‘DEFAULT’ in
>>>>> jdk7/langtools/src/share/classes/com/sun/tools/javac/code/Source.java
>>>>> suggest a documentation bug: the text “This is the default value. ”
>>>>> should be moved from the description for -source 1.6 to 1.7.
>>>>>
>>>>> Seems that it was forgotten to update the documentation for -source
>>>>> before the JDK 7 release; the documentation for -target looks up to date.
>>>>>
>>>>> The man page for JDK 8 needs to be updated accordingly (DEFAULT is
>>>>> JDK1_8 in this case).
>>>>>
>>>>> The javac documentation on the web (…/solaris/… and …/windows/…) is also
>>>>> affected. Is the javac for Windows documentation generated from the man
>>>>> page?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.openjdk.java.net/pipermail/compiler-dev/attachments/20111116/d5b60b89/attachment.html