RFR of JDK-8176563: @since value errors in apis of java.base/java.logging module

David Holmes david.holmes at oracle.com
Wed Mar 15 00:39:04 UTC 2017


Hamlin,

I have to agree with Martin here. These changes seem very misguided in 
places. Only NEW types or new type members should be flagged with @since.

For example, adding "@since 9" to java.lang.reflect.Field.setAccessible 
is just WRONG!

David

On 15/03/2017 2:06 AM, Martin Buchholz wrote:
> On Tue, Mar 14, 2017 at 12:46 AM, Hamlin Li <huaming.li at oracle.com> wrote:
>
>>
>> @since *since-text*
>>
>> Introduced in JDK 1.1
>>
>> Adds a *Since* heading with the specified since-text value to the
>> generated documentation. The text has no special internal structure. This
>> tag is valid in any documentation comment: overview, package, class,
>> interface, constructor, method, or field. *This tag means that this
>> change or feature has existed since the software release specified by the*
>>  *since-text* *value*, for example: @since 1.5.
>>
>> For Java platform source code, the @since tag indicates the version of
>> the Java platform API specification, which is not necessarily when the
>> source code was added to the reference implementation. Multiple @since tags
>> are allowed and are treated like multiple @author tags. You could use
>> multiple tags when the program element is used by more than one API.
>>
> Instead of focusing on the *red text*, I read
>
>
> """For Java platform source code, the @since tag indicates the version of
> the Java platform API specification"""
>
>
> as being all about API, not implementation.  There is no @modifiedIn or
> @optimizedIn tag
>


More information about the core-libs-dev mailing list