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 -------------- next part -------------- An HTML attachment was scrubbed... URL: http://lists.amdatu.org/pipermail/amdatu-developers/attachments/20101012/065bdbbf/attachment.html
