Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
[cdt-dev] API tooling: @noimplement, @noextend, ...

Since CDT 4.0 the documentation of ILanguage explicitly states that clients are not allowed to implement the
interface, so adding the @no... tags is no breakage.
By the Eclipse API guidelines implementing or extending classes/interfaces is forbidden unless stated otherwise in the javadoc ( So in general it is no breakage to add @no... tags to classes or interfaces.
This situation will change for the first release after CDT 6.0, because the javadoc tags of the API tooling are exported to the .api_description file in the plugin (automatically starting with 3.5M5: With that, clients of CDT plugins can use the API tooling to verify correct usage of CDT apis. Furthermore, if the baseline contains .api_description files, the API tooling reports adding such a tag as API breakage.
--> It is important for us to add the tags to all interfaces and classes that are not intended to be implemented/extended. See a discussion on that here:
CDT probably does contain interfaces/classes that are intended to be implemented/extended where the java-doc does not explicitly state that. In such a case we certainly must not add the @no... tags, rather than that the java-doc needs to be updated. I am not aware of a class/interface that has been marked as @no.. where this should not be the case.
So adding @no... tags is important and it is not for the purpose of hiding API breakage. If we end up with breaking changes, we need to increment the plugin version.

From: cdt-dev-bounces@xxxxxxxxxxx [mailto:cdt-dev-bounces@xxxxxxxxxxx] On Behalf Of Mike Kucera
Sent: Thursday, January 08, 2009 6:10 PM
To: CDT General developers list.
Subject: Re: [cdt-dev] Resetting API-tooling preferences.
Importance: Low

I committed those changes by accident. Sorry for the inconvenience.

But now that you mention it I do have some issues with the API tooling:
- The API tooling cannot detect breaking changes to contracts, which is one of the easiest ways that you can break API. For example if you have a method that's originally documented to not return null, and you change it so that it does return null, there is no change to the method signature, but any client code that does not check for null will be broken. The API tooling does not catch this. Its really important to understand that if the API tooling isn't reporting any errors that does NOT mean that breaking API changes don't exist.
- The proliferation of javadoc tags just to get the API tooling to shut up. For example ILanguage is now annotated as @noimplement and @noextend. This is wrong because the ILanguage interface IS intended to be implemented by clients. You can't add a language to CDT without implementing this interface. These tags were added hastily just to get the API errors to go away.

If we were making a point release were we had a strict rule to not break any API at all then the story would be different. But it seems we are allowing API breakage in the core but just using the API tooling to minimize the breakage or at least report on what has been broken.

Perhaps we should change the way we use the API tooling. Sometimes when there is a breaking change, like adding a field to ILanguage, we should not be annotating the class with javadoc tags in order to suppress the errors. Instead create a comparability problem filter for the error (Plug-in Development > API Problem Filters). With this approach we end up with a nice list of breaking changes in the problem filters dialog and we don't have to add inappropriate javadoc tags.

What do you think?

Mike Kucera
Software Developer
IBM Eclipse CDT Team

Inactive hide details for "Schorn, Markus" ---01/08/2009 05:14:38 AM---Hi Mike, You have changed the configuration of the API t"Schorn, Markus" ---01/08/2009 05:14:38 AM---Hi Mike, You have changed the configuration of the API tooling in the core-plugin. I have undone these changes


"Schorn, Markus" <Markus.Schorn@xxxxxxxxxxxxx>


"CDT General developers list." <cdt-dev@xxxxxxxxxxx>


01/08/2009 05:14 AM


[cdt-dev] Resetting API-tooling preferences.

Hi Mike,
You have changed the configuration of the API tooling in the core-plugin. I have undone these changes
so that API breakage is again reported as an error, rather than a warning.

Do you really want to change these settings, why?
cdt-dev mailing list

Back to the top