Community
Participate
Working Groups
The API Tools documentation should specify: (1) The format of @since tags: "@since 3.4", "@since org.eclipse.core.filesystem 1.0", "@since 3.4, protected since 3.1" (stuff after the version number is uninterpreted free text). (2) How @since info is propagated: (2.a) From an enclosing element to its members (e.g. from type to methods declared in the type, or to nested types). (2.b) From a method to overriding/implementing methods. For (2.b) e.g. the situation from bug 240651 comment 8 should be clarified: Should all overriding methods get a Javadoc with a separate @since tag, or is it enough to add @since in the top declaration(s)? I remember we also had situations where a base method was added in plug-in org.eclipse.a 3.1, and the overriding method was at the same time added in plug-in org.eclipse.b 3.4. Note that the Javadoc tool does not copy @since tags from overridden methods. The Javadoc hovers in recent 3.5 builds also don't copy @since tags any more.
See also bug 233445.
Created attachment 138336 [details] new doc
applied patch to HEAD
.
The document says under "Malformed @since tags": API tools checks that all @since tags follow the general format of: [@since] [pre-amble] [2 part version] [post-amble] Is it still correct that API Tooling does not interpret the pre-amble as e.g. suggested in http://wiki.eclipse.org/index.php/Version_Numbering#Which_version_to_use_in_javadoc_tags ?
(In reply to comment #5) > Is it still correct that API Tooling does not interpret the pre-amble as e.g. > suggested in > http://wiki.eclipse.org/index.php/Version_Numbering#Which_version_to_use_in_javadoc_tags > ? > Correct, we do not interpret anything except the version number. For example: /** * @since org.eclipse.debug.core DebugElement 3.5 - new method */ public void method1() {} is a valid tag as far as API tools is concerned.
