|Re: [cdt-dev] Resetting API-tooling preferences.|
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?
IBM Eclipse CDT Team
"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.
Back to the top