Community
Participate
Working Groups
Build Identifier: Version: 3.7.0 Build id: I20110613-1736 In the classes InstanceScope, ConfigurationScope, DefaultScope the @since tag on field INSTANCE indicates that this field has been added in version 3.4 of Eclipse. This is also visible in the web doc: http://help.eclipse.org/indigo/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/api/org/eclipse/core/runtime/preferences/InstanceScope.html http://help.eclipse.org/indigo/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/api/org/eclipse/core/runtime/preferences/ConfigurationScope.html http://help.eclipse.org/indigo/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/api/org/eclipse/core/runtime/preferences/DefaultScope.html This is wrong. In fact, it has been added in version 3.4 of the org.eclipse.equinox.preferences plug-in, which corresponds to version 3,7 of Eclipse. I have checked the source code: Eclipse 3.6: plugins/org.eclipse.equinox.preferences.source_3.3.0.v20100503.jar Eclipse 3.7: plugins/org.eclipse.equinox.preferences.source_3.4.0.v20110502.jar This was also mentioned in comment 9 in https://bugs.eclipse.org/bugs/show_bug.cgi?id=364464 This bug is quite harmful because it makes people rely on APIs that they think are old, when they are in fact relatively new. Reproducible: Always Steps to Reproduce: Try to use org.eclipse.core.runtime.preferences.ConfigurationScope.INSTANCE in Eclipse 3.6. The compiler signals an error.
As stated in bug364464 comment14 the @since tag indicates the bundle version, not the product version which the bundle happens to be included in.
(In reply to comment #1) > @since tag indicates the bundle version, > not the product version which the bundle happens to be included in. This makes sense for plug-ins that come from outside Eclipse and necessarily have their own release schedule, for example com.ibm.icu, javax.servlet, org.junit, and similar. But for the plug-ins from eclipse.org it causes two problems: 1) There are 174 plug-ins from org.eclipse in Eclipse 3.7 (classic). How is a developer meant to know the version history (and hence the age of each version) by heart? A @see tag is meant to tell whether you can rely on this API if you assume a recent enough Eclipse. Where "recent enough" is defined by version number or by age. So the full information I would want to know is @since 3.4 (Eclipse 3.6, June 2008) In practice it is just too tedious to look up this information. Why can't all of org.eclipse.* plug-ins not follow the same numbering scheme? It works for org.eclipse.swt and 30 other among the 174 plug-ins. Why not for the other 143 ones as well? 2) The reader of the reference manual http://help.eclipse.org/indigo/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/api/org/eclipse/core/runtime/preferences/InstanceScope.html does not even know in which plug-in a certain package is located. There is no link from the package org.eclipse.core.runtime.preferences or the class org.eclipse.core.runtime.preferences.InstanceScope to the plug-in org.eclipse.equinox.preferences, To make the @since tags transparent in the reference manual, such information would have to be added to it. I'm reopening and changing the title to "since tags in javadoc generated documentation should be accompanied with product release version and product release date".
My view is going to contradict your view a bit. I would prefer to actually version our API packages individually and base the @since tag on the actual package version, not the bundle version which the package just happens to be included in. (In reply to comment #2) > In practice it is just too tedious to look up this information. I agree, moving to PDE api tooling for help. Perhaps there is some way to make this easier to determine. I really don't think forcing content from other projects (such as Equinox) that get consumed by the Eclipse (SDK) project should dictate what Equinox source code uses for the @since tag is reasonable. The Eclipse (SDK) project now consumes many things from other projects at the foundation (e.g. Equinox, Jetty, ECF, EMF). There is no way the Eclipse (SDK) project can force or dictate all these other projects to use @since tags that match the release the Eclipse (SDK) project happens to include them in. And don't get me started with what we would do for the 4.x vs 3.x Eclipse (SDK) project streams if we had to somehow coordinate @since tags between the different projects that the Eclipse (SDK) project consumes!
(In reply to comment #3) > I really don't think forcing content from other projects (such as Equinox) that > get consumed by the Eclipse (SDK) project should dictate what Equinox source > code uses for the @since tag is reasonable. The Eclipse (SDK) project now > consumes many things from other projects at the foundation (e.g. Equinox, > Jetty, ECF, EMF). There is no way the Eclipse (SDK) project can force or > dictate all these other projects to use @since tags that match the release the > Eclipse (SDK) project happens to include them in. > > And don't get me started with what we would do for the 4.x vs 3.x Eclipse (SDK) > project streams if we had to somehow coordinate @since tags between the > different projects that the Eclipse (SDK) project consumes! This. Changing the approach to packages or products has merits, but would be significant work to convince teams to take up the new strategy. This is not something API tools will be picking up.
javadoc and the specification of the @since tag were defined 15 years ago, assuming the entire code is packaged into a single product. Eclipse, with the ability to package plug-ins from several sources in a single product, has gone beyond this simple model. But the tools (in particular javadoc) did not catch up. What we need is an adaptation of javadoc, so that when it creates the javadoc of the entire Eclipse, 1) For each class, it displays the plug-in in which the class is located. This is necessary because when I use a class, I have to add a dependency to its plug-in to my plug-in's dependencies. The "quick fix" does not do it. 2) For a @since tag, it is able to infer the product version and release date and put it into the generated HTML. Some customization is required for this to work, of course. The result should be that when a .java class contains @since 3.4 the following HTML is generated for an org.eclipse.swt class: Since: org.eclipse.swt 3.4 (Eclipse 3.4, June 2008) whereas the following HTML is generated for class org.eclipse.core.runtime.preferences.InstanceScope: Since: org.eclipse.equinox.preferences 3.4 (Eclipse 3.7, June 2011) Additionally, a tabular view of the release history of plug-ins may be useful: | Eclipse | Eclipse | Eclipse | Eclipse | | 3.4 | 3.5 | 3.6 | 3.7 | --------------------------------+---------+---------+---------+---------+ Release date |June 2008|June 2009|June 2010|June 2011| --------------------------------+---------+---------+---------+---------+ org.eclipse.swt | 3.4 | 3.5 | 3.6 | 3.7 | org.eclipse.equinox.preferences | 3.2.200 | 3.2.300 | 3.3.0 | 3.4.0 | com.ibm.icu | 3.8.1 | 4.0.1 | 4.2.1 | 4.4.2 | ... | | | | | --------------------------------+---------+---------+---------+---------+
That is an interesting proposal. Looking for somewhere outside of PDE to move this bug for discussion.
Closing after 8 years of inactivity.
