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<mailto:ivo.ladage-vandoorn at gxsoftware.com> | www.gxsoftware.com<http://www.gxsoftware.com> | twitter.com/GXSoftware<http://twitter.com/GXSoftware> -------------- next part -------------- An HTML attachment was scrubbed... URL: http://lists.amdatu.org/pipermail/amdatu-developers/attachments/20101011/dc4f7aa4/attachment-0001.html
