> 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
