The main point of the discussion seems to be the way we want to document our
API for developers building applications on top of Amdatu. Note that I am
really only talking about this particular use case. There are several options:
- Publish javadoc of all classes and mention 'somewhere' (where?) what classes
are part of the API and what are not.
- Publish javadoc of all classes and use package naming conventions like
".api", "impl" and/or ".internal" to indicate what classes belong to the public
API. This is a common approach, used for example in the Jackrabbit and Pax
projects.
- Publish javadoc only for classes that are supposed to be part of the public
API.
Concerning the remark; "The project object model is specifically intended to
hold such metadata and we can solve this in the maven build/release
configuration."
The point is that this is not as easy as it seems, which is the reason I
started this threat. If you do this in maven files, you will need a lot of
manual configuration which need to be changed as soon as a subpackage is added
or removed.
I still believe the doclet approach is the best approach available. It provides
an easy way to tag classes and interfaces as not being part of the public API.
It prevents that you need to refactor packages and add tons of manual
configuration (excluding each individual subpackage) to maven files. It is the
cleanest approach since with this approach you can still generate all javadoc
("amdatu-javadoc-all.jar" needed by some Developers like Bram ;->) and the
javadoc for only the public API ("amdatu-javadoc-api.jar").
I don't see the real problem with using this special annotation.
Regards, Ivo
-----Original Message-----
From: amdatu-developers-bounces at amdatu.org
[mailto:[email protected]] On Behalf Of Bram de Kruijff
Sent: dinsdag 12 oktober 2010 11:51
To: amdatu-developers at amdatu.org
Subject: Re: [Amdatu-developers] Package naming versus automated javadoc
generation
> So except from explicitly stating it on the website, we should hide it from
> our API documentation, which can easily be done using the Doclet approach
> (just add the @exclude annotation to the interface)
Here is why I don't like it. As a developer I expect to get full javadoc for
any library. When I have a dependency on bladiebla.jar I expect my IDE to
attach bladiebla-javadoc.jar and provide me with good inline documentation.
What you are proposing now is that you actually hide javadoc for
interfaces/classes that I am seeing in the jar. So instead of reading "be
carefull" I get nothing. Maybe your argument is actually ammunition for the
'split the artifacts fraction' which would solve your problem ;)
What you are looking for is a specific subset tailored to 'users' of the
platform, the public service API for application developers and as you describe
this does not even map 1-1 on public/exported packages at the OSGi level (as
Marcel assumed) but even has some more knowledge to it. There are different
'views'. So I'm thinking make this a packaging/release problem. Do not put it
in the code through additional packagename conventions, annotations, etc. The
project object model is specifically intended to hold such metadata and we can
solve this in the maven build/release configuration.
An approach (without splitting api in svn) I am thinking of:
1) Before release assembly
2) Aggregate relevant application API sourcefiles
3) Generate the javadoc from that
4) Include it in the release
5) Put it on the wiki
Just a thought, something like that, and yes we could wrap that in a custom
plugin to make our lives easier.
Grz
Bram
From: amdatu-developers-bounces at amdatu.org
[mailto:[email protected]] On Behalf Of Ivo Ladage-van Doorn
Sent: Tuesday, October 12, 2010 10:00 AM
To: amdatu-developers at amdatu.org
Subject: Re: [Amdatu-developers] Package naming versus automated javadoc
generation
Btw, writing a custom plugin would still solve nothing; the problem is not in
the plugin but in the javadoc tool itself. Thinking of it, I would suggest
solution 3, the Doclet approach. Refactoring package names only for better
javadoc generation wouldn't be a good thing, but even that wouldn't solve it
all. A good example is the CassandraDaemonService. This service interface for
the Cassandra daemon is used by other Cassandra bundles (listener, persistence
manager) but should not be used directly by Amdatu developers. Especially with
Cassandra 0.7 things can go wrong seriously when directly using the Cassandra
server to register keyspaces and CF's. So except from explicitly stating it on
the website, we should hide it from our API documentation, which can easily be
done using the Doclet approach (just add the @exclude annotation to the
interface)
Regards, Ivo
From: amdatu-developers-bounces at amdatu.org
[mailto:[email protected]] On Behalf Of Ivo Ladage-van Doorn
Sent: dinsdag 12 oktober 2010 9:40
To: amdatu-developers at amdatu.org
Subject: Re: [Amdatu-developers] Package naming versus automated javadoc
generation
For an illustration of the "javadoc problem", I posted an example of the
current Javadoc to http://repository.amdatu.org/sites/apidocs/
My point is that if you are a developer that builds components on top of
Amdatu, you should be able to read javadoc of classes that you are supposed to
use. In the example you see about 20 occurrences of the class "Activator", one
for each bundle. These classes are completely irrelevant for this developer. In
fact the majority of the classes are irrelevant (only 11 of the 60 packages).
OSGi activators, service implementation classes and much more are just classes
that this developer should not use or depend on. So why publish javadoc of all
classes when only 10% of these classes should be used?
I agree with Angelo that next to the javadoc for this kind of developer, we
will also need javadoc for an Amdatu developer. For a developer building on
Amdatu, all classes are relevant and the javadoc should describe all classes
(even private)? But that is a different use case.
Regards, Ivo
From: amdatu-developers-bounces at amdatu.org
[mailto:[email protected]] On Behalf Of Marcel Offermans
Sent: maandag 11 oktober 2010 23:36
To: amdatu-developers at amdatu.org
Subject: Re: [Amdatu-developers] Package naming versus automated javadoc
generation
Remark: I started writing this this afternoon, but didn't get to finish the
mail until now. ;)
On 11 Oct 2010, at 16:04 , Ivo Ladage-van Doorn wrote:
In most Apache projects it is standard to use the root package for public API
classes (for example service interfaces).
Now this causes an issue with automated javadoc generation. When using the
maven-javadoc-plugin it seems that you cannot specify to include javadoc for
the root package but omit javadoc of all subpackages without explicitly
excluding all existing subpackages.
Formally, there is no such thing as a subpackage, packages are a "flat"
namespace.
But basically the problem you're trying to solve is to generate only JavaDoc
for the API, in other words all exported packages? To properly do that we have
to have a plugin that really understands OSGi bundles and gets the metadata
from the pom.xml. Anything else is probably too easy to break. So, in short, I
really would like to solve this in the plugin instead of enforcing conventions
on package names.
Also, reading the other responses right now, I'm not so sure why it's important
to create just Javadoc for our API. We have already defined what our API is in
other places, so people should be able to figure out what they can use. If we
really want to create docs for our APIs, my workaround (if we don't fix the
plugin) would be to explicitly list all packages.
Greetings, Marcel
_______________________________________________
Amdatu-developers mailing list
Amdatu-developers at amdatu.org
http://lists.amdatu.org/mailman/listinfo/amdatu-developers
