[
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.
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: https://bugs.eclipse.org/bugs/show_bug.cgi?id=255862).
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.
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.
Markus.
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
mkucera@xxxxxxxxxx
"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
From: |
"Schorn, Markus"
<Markus.Schorn@xxxxxxxxxxxxx> |
To: |
"CDT General developers list."
<cdt-dev@xxxxxxxxxxx> |
Date: |
01/08/2009 05:14 AM |
Subject: |
[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?
Markus._______________________________________________
cdt-dev
mailing list
cdt-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/cdt-dev
