[pde-dev] [api tooling] Re: ApiTools_Architecture

[Darin Wright <Darin_Wright@xxxxxxxxxx>]

> 
> When is a good time to provide feedback?

Anytime. The sooner we get feedback, the better. I'm posting your note to 
pde-dev for the benefit of all interested.

> 
> One thing that caught my eye immediately was the list of new Javadoc 
tags:
> 
> @nosubclass - This class is not intended to be subclassed. 
> @noinstantiate - This class is not intended to be instantiated. 
> @noimplement - This interface is not intended to be implemented by 
clients. 
> @noreference - This type is not intended to be referenced by clients.
> 
> It seems that for the first two, you should add "...by clients" as 
> well.

Well, that is a good point. It could be that a class is not intended to be 
subclassed at all (clients or internally - basically a final class). 
However, it is more important that clients do not subclass, so we could 
add "by clients". The similar situation may be true for @noinstantiate - 
i.e. a utility class with only static methods.

> I assume "clients" refers to anyone outside of the current 
> bundle? How do you express exceptions for friends such as test bundles?

So far, exceptions are handled by x-friends in a Manifest.MF, rather than 
javadoc tags. However, friends were intended to have API access to classes 
that are internal/private - friends were not intended to override the 
restrictions above. So, we need to think about how that might work.

Currently, there is no concept of SPI (service provider interface) - an 
API interface for a select few. However, we were thinking of adding 
special tags in the Manifest to represent this. I could also imagine 
adding special tags to allow tests suites/clients to have unrestricted 
access to packages/bundles.

> 
> You are only talking about using these annotations for types. We 
> have similar constraints for methods and fields. For example, SWT 
> has public fields that could be marked with @noreference.  If 
> @noreference was available for constructors, wouldn't that be a good
> replacement for @noinstantiate?   I'm sure that we also have methods
> that are @nooverride.

Yes - we intend to extend the mechanisms to members. Jeff suggested that 
we might use @noextend for both types and methods.

Thanks,

Darin