Adding @since tags

[Richard Bair]

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. 

> 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.

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.

Richard