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
