Adding @since tags

[Pavel Safrata]

Hi Richard,

On 28.5.2013 17:37, Richard Bair wrote:
> Hi Pavel,
>
> This sounds great!
>
>> I'm almost ready with a tool that generates @since tags to JavaFX API. My question is what should I generate. Essentially, there are three releases with added API: 2.0, 2.2 and 8.0.
> How does it work? Specifically, if an API was not tagged in 2.2, and is not tagged in 8.0, how do you determine which release the API appeared in? Are you searching through the generated javadocs? A tool I've wanted for many years but haven't had to time to write would be one that would catch new public API changes that haven't been reviewed, and list all the new API at the end of the release that we could then use as the basis for slides / presentations / release notes / etc.

I take two jars from subsequent releases, use SigTest to list API 
differences, then go over the results, find the added entities in 
sources and add/update the javadoc tag.

>
>> Question 1:
>> Should we generate @since for the initial stuff that appeared in 2.0?
> I think so.
>
>> Question 2:
>> There are classes and methods marked as "@since JavaFX 1.3" (comments survived porting to Java). Should I keep it? Or remove/replace by 2.0 based on Q1? Note that I'm not able to compare Java 2.0 API to previous fx-script API so I cannot make sure everything that existed before 2.0 is marked properly as 1.x.
> I would replace all the @JavaFX 1.x with whatever the answer to Question 3 is.
>
>> Question 3:
>> What should be the format?
>>
>> (a) - full FX version
>> 2.0: @since JavaFX 2.0
>> 2.2: @since JavaFX 2.2
>> 8.0: @since JavaFX 8.0
>>
>> (b) - major FX version
>> 2.0: @since JavaFX 2
>> 2.2: @since JavaFX 2
>> 8.0: @since JavaFX 8
>>
>> (c) - JDK version
>> 2.0: @since 1.7
>> 2.2: @since 1.7
>> 8.0: @since 1.8
>>
>> Or something else?
> Right now I think I'd say (a), the full FX version is what we ought to go with for now. At first ( c ) looked like the best option,  however, we then have the oddity that @since 2.0 happened before @since 1.8! Also, 2.0 was shipped with 1.6 as well as 1.7 so @since 1.7 isn't entirely accurate.
>
> If/When FX goes through the JCP process, it will at that time be standardized and we might reset the clock, such that everything at that time is upgraded to 1.9 as the "since" version.

OK, if there are no other concerns I'll go with (a).

>
> Another question, when a class is added in a release, do you add @since to the class but *not* the methods, or do you tag both the class and the methods? It seems more foolproof to tag both the class & methods, but I don't think that is how they do it on the JDK side.

I add it only to the class. Indeed, this is the JDK practice. SigTest 
reports new class as a single change, so right now I don't have input 
for adding it everywhere. I think I could go over the new classes, add 
empty classes with the same names to the old jar and then use the tool 
to generate the tags for the API difference which will now be all the 
contents of the classes. Do you think it's worth the effort?

Thanks,
Pavel

>
> Richard