[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
[pde-dev] [api tooling] Re: ApiTools_Architecture
|
>
> 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