Re: [linuxtools-dev] API for 1.0

[Aleksandar Kurtakov <akurtako@xxxxxxxxxx>]

Oh, and one more thing. Please cd into your subproject and run mvn javadoc:aggregate. This will print out a number of lines like:
[WARNING] /home/akurtakov/git/org.eclipse.linuxtools/lttng/org.eclipse.linuxtools.tmf.core.tests/stubs/org/eclipse/linuxtools/tmf/stubs/request/TmfEventRequestStub.java:29: warning - @param argument "range" is not a parameter name.

If we're going to be serious for API we need to have proper javadoc that at least matches the arguments passed. Note that while having good javadoc is nice thing in general it's a must have if you define API. The warnings printed by the build are only from the classes exposed. I really encourage the subprojects to create a per-project Java Compiler/Errors/warnings configuration and to enable more warnings than the defaults especially for these things so more people see them and fix them as they do other things.

Clean subprojects from that point of view are: gcov, gprof, man, rpmstubby, rpm, perf, valgrind

Alex

----- Original Message -----
> From: "Aleksandar Kurtakov" <akurtako@xxxxxxxxxx>
> To: "Linux Tools developer discussions" <linuxtools-dev@xxxxxxxxxxx>
> Sent: Thursday, March 22, 2012 9:22:54 PM
> Subject: 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
> > 
> _______________________________________________
> linuxtools-dev mailing list
> linuxtools-dev@xxxxxxxxxxx
> https://dev.eclipse.org/mailman/listinfo/linuxtools-dev
>