----- Original Message ----- > From: "John Arthorne" <john_artho...@ca.ibm.com> > To: "Andrew Overholt" <overh...@redhat.com>, "Linux Tools developer > discussions" <linuxtools-dev@eclipse.org> > Sent: Thursday, March 22, 2012 8:48:33 PM > Subject: Re: [linuxtools-dev] API for 1.0 > > > 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 ;)
Sadly, you're right - though a lot has been hidden in the last month. > > 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. I fully support the all-internal approach and after doing that to the man-page and rpmstubby projects they have two exported classes each. In the rpmstubby case it even led to simplifying/unifying the codebase. But I think that we should use the internal package name convention wherever possible to make clear difference and not make the javadoc building more complicated. I would even ask for renaming things that are not supposed to be api to internal or provisional(if you prefer) and export the package(if you have to) and mark as an x-internal. What we have in non internal(provisional) packages should really be API. Alex > > 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 > _______________________________________________ > linuxtools-dev mailing list > linuxtools-dev@eclipse.org > https://dev.eclipse.org/mailman/listinfo/linuxtools-dev > _______________________________________________ linuxtools-dev mailing list linuxtools-dev@eclipse.org https://dev.eclipse.org/mailman/listinfo/linuxtools-dev
