[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
Re: [linuxtools-dev] API for 1.0
|
----- Original Message -----
> From: "John Arthorne" <John_Arthorne@xxxxxxxxxx>
> To: "Andrew Overholt" <overholt@xxxxxxxxxx>, "Linux Tools developer discussions" <linuxtools-dev@xxxxxxxxxxx>
> 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@xxxxxxxxxxx
> https://dev.eclipse.org/mailman/listinfo/linuxtools-dev
>
