> 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. If you want to generate the javadoc for > the Amdatu API (which includes the interfaces but not the internal > implementation classes) in the example above you would need to include > org.amdatu.platform.sesame.application and explicitly exclude all its > subpackages; org.amdatu.platform.sesame.application.service and > org.amdatu.platform.sesame.application.osgi. When new subpackages are added, > these need to be excluded as well in the maven javadoc plugin. And so this is > an error-prone approach needing a lot of manual configuration.
Maybe the real question is how we define and handle the "Amdatu API". My thoughts at this point: -> Not sure if framework/foundation services like Sesame are/should be part of the "Amdatu API" (but that is another discussion) [Ivo Ladage-van Doorn] With the "Amdatu API" I mean all services/interfaces that developers building bundles on top of the Amdatu platform may use. The SesameService is part of the semanticweb subproject and is a service that external developers might want to use. So yes, I would expect the SesameService to be documented with javadoc and the javadoc to be available on the (semanticweb sub-)project website. -> Is this really an issue or just a bug/cr for the javadoc plugin and should we just cope for now (or even fixed it in the plugin)? [Ivo Ladage-van Doorn] It is a known restriction in the javadoc tool, see http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4074234 -> I do not like any of the proposed solutions very much. They all have kind of a workaround smell about them. -> Do we actually really need/want to hide implementation classes from javadoc at this point? [Ivo Ladage-van Doorn] I think yes. If reading the javadoc from the Amdatu website, I should see the javadoc of the TenantManagementService but the javadoc of the TenantManagementServiceImpl should be hidden from me since I am not supposed to do anything with it. -> If you really think of an API/SPI as being something separate of an implementing bundle why not split the artifacts? (solution 4) [Ivo Ladage-van Doorn] Splitting the artifacts wouldn't solve anything as long as the package names remain the same. Regards, Bram From: amdatu-developers-bounces at amdatu.org [mailto:[email protected]] On Behalf Of Ivo Ladage-van Doorn Sent: Monday, October 11, 2010 4:04 PM To: amdatu-developers at amdatu.org Subject: [Amdatu-developers] Package naming versus automated javadoc generation Hi All, In most Apache projects it is standard to use the root package for public API classes (for example service interfaces). Internal classes (like the OSGi activator and a service implementation) are added to a subpackage of that root package. We use the same convention for Amdatu, for example: org.amdatu.platform.sesame.application.SesameService -> interface of the sesame service org.amdatu.platform.sesame.application.service.SesameServiceImpl -> Implementation of the sesame service org.amdatu.platform.sesame.application.osgi.Activator -> OSGi activator of the service 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. If you want to generate the javadoc for the Amdatu API (which includes the interfaces but not the internal implementation classes) in the example above you would need to include org.amdatu.platform.sesame.application and explicitly exclude all its subpackages; org.amdatu.platform.sesame.application.service and org.amdatu.platform.sesame.application.osgi. When new subpackages are added, these need to be excluded as well in the maven javadoc plugin. And so this is an error-prone approach needing a lot of manual configuration. For that reason the convention used by GX is to put interfaces in a subpackage called api. An alternative approach would be to introduce the convention that all internal classes should reside in a subpackage called internal. Also custom doclets could be used to support excluding explicit classes. So (some) possible solutions are: Solution 1 org.amdatu.platform.sesame.application.api.SesameService -> interface of the sesame service org.amdatu.platform.sesame.application.service.SesameServiceImpl -> Implementation of the sesame service org.amdatu.platform.sesame.application.osgi.Activator -> OSGi activator of the service Solution 2 org.amdatu.platform.sesame.application.SesameService -> interface of the sesame service org.amdatu.platform.sesame.application.internal.service.SesameServiceImpl -> Implementation of the sesame service org.amdatu.platform.sesame.application.internal.osgi.Activator -> OSGi activator of the service solution 3 Use ExcludeDoclet from com.sixlegs.misc to implement @exclude javadoc annotation. Disadvantage that you will still need to explicitly tag classes with @exclude that are not supposed to be part of the public API. Advantage is that this also allows public methods/fields to be excluded from the API (though it is doubtful whether you should need this) What solution would you prefer or does anyone have a better idea? Regards, Ivo GX | Ivo Ladage-van Doorn | Product Architect | Wijchenseweg 111 | 6538 SW Nijmegen | The Netherlands | T +31(0)24 - 388 82 61 | F +31(0)24 - 388 86 21 | ivo.ladage-vandoorn at gxsoftware.com | www.gxsoftware.com | twitter.com/GXSoftware _______________________________________________ Amdatu-developers mailing list Amdatu-developers at amdatu.org http://lists.amdatu.org/mailman/listinfo/amdatu-developers
