> 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) -> 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)? -> 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? -> If you really think of an API/SPI as being something separate of an implementing bundle why not split the artifacts? (solution 4) 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
