Community
Participate
Working Groups
I20080415-1646 I still think the @no* tags should stand for themselves and the boilerplate description (usually redundant, but who knows?) is counterproductive. Nevertheless, the API tools do implement a certain specification by producing the 'API Use' problems. That specification should be made readily available in the SDK. It should appear - on hover - in content assist as additional info - in help, especially for the 'API Errors/Warnings' preference/properties page The specification should say more than the boilerplate, e.g. whether @nooverride is redundant for a method that is already tagged with @noreference (maybe not, if you want to support the case of a method that can be extended by client subclasses but should not be called from client code).
Another unclear field is @noimplement and @noextend for interfaces. - Does one imply the other? - Do they work transitively? E.g. with an @noimplement interface I, can a client write an interface IExtension extends I, and then implement IExtension? Another topic: Why does content assist not offer @noreference for interfaces?
We don't offer @noreference for types as this would mean that the type is not API inside an API package.
@noimplement and @noextend are not the same... The way they *work* currently is by explicit keywords. If you have "X implements Y" then we apply any @noimplement rules. If you "X extends Y", we apply any @noextend rules. So, if you have an inteface marked as @noimplement, others could extend it. And if you have an interface marked as @noextend, others could implement it. If a client has an interface "X extends Y", and then implements X, they are not currently flagged as illegally implementing Y (if Y is marked as @noimplement). However, this feels slightly wrong for interfaces... generally if you can't implement X, you should probably not be allowed to implement an extension of X. (Although one could imagine that an interface not be allowed to be implemented alone, but only in conjunction with another interface). We should clarify this, as currently you would also need @noextend on interfaces marked as @noimplement to catch problems.
(In reply to comment #3) I would just remove @noimplement and use @noextend everywhere. This also solves all transitivity problems. I don't see the value of having two tags. Can somebody come up with a real example that shows lost functionality when the two are merged?
FYI - I've added doc to the reference section of the PDE user doc to describe the supported tags and their semantics. I've tried to keep the doc "positive" to describe where the tags are supported and what they mean rather than the "negative" (where they are *not* supported and what they *don't* mean). The jury is still out on the whether @noimplement should also implicitly mean @noextend for interfaces (although I am starting to lean that way).
@noimplement will also mean @noextend for interfaces. We will keep the @noimplement tag as it conveys the message "not to implement" better than @noextend.
Fixed. @noimplement also means @noextend for interfaces. Updated doc and search conditions to flag this as an error.
Please verify, Mike.
verified
