Re: [linuxtools-dev] API for 1.0

[John Arthorne <John_Arthorne@xxxxxxxxxx>]

Andrew Overholt wrote on 03/21/2012 02:25:42 PM:
> Please take a look at the Javadocs for our nightly build:
> 
>   https://hudson.eclipse.org/hudson/job/linuxtools-master/javadoc/
> 
> There is still a *lot* of API exposed.  If that's intention,
great, but
> if not, we need to fix it ASAP.

From a quick glance, that looks like a code base that
doesn't make any distinction between API and non-API ;)

The first class I saw in the first package was an
Activator, which presumably means clients are welcome to stop your bundles
whenever they feel like it?  Rather than asking "what should
we wide", I would suggest the default assumption be that all packages
are internal and instead ask "what should we expose".. ie..,
what is actually useful for clients to use/extend, unlikely to ever change,
etc. Note you don't have to do this with package naming conventions like
".internal" if you don't want to. Adding x-internal to the bundle
manifest and removing it from the generated javadoc list helps to make
it clear what is meant to be used by clients.

For anyone who hasn't seen it, there is a good "API
101" presentation here:

http://www.eclipse.org/eclipse/development/apis/Eclipse-APIs-Lines-in-the-Sand.pdf

John