> Regardless of the javadoc, there is some necessity to 'hiding' implementation > classes using a naming scheme: we will want to build api jars, which should > only contain interface packages. So, the 'workaround smell' isn't all too > bad, we will need the structure anyway.
Ok, but the maven mantra will say that if you need seperate artifacts you must create seperate artifacts (as in projects). Then you can do a aggregate on the javadoc of either api only or both. Not sure if maven will let you create different artifacts (and their respective javadoc targets) in a nice way? regards, Bram ________________________________________ From: amdatu-developers-bounces at amdatu.org [amdatu-developers-bounces at amdatu.org] On Behalf Of Angelo van der Sijpt [[email protected]] Sent: Monday, October 11, 2010 6:20 PM To: amdatu-developers at amdatu.org Subject: Re: [Amdatu-developers] Package naming versus automated javadoc generation The matter of whether you would like to hide implementation javadoc or not, depends on your goal with the generator javadoc. If it is intended to be used as an API (e.g., as a developer, I point my javadoc location to this, and have meaningful code completion in Eclipse), it sounds reasonable to hide the implementation, but it's not necessary. If you intend it as documentation, we should include all classes. Regardless of the javadoc, there is some necessity to 'hiding' implementation classes using a naming scheme: we will want to build api jars, which should only contain interface packages. So, the 'workaround smell' isn't all too bad, we will need the structure anyway. All said and done, I prefer something like 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 perhaps even stripping out the 'service' package, since it has no meaning anyway. Angelo On Oct 11, 2010, at 5:05 PM, Ivo Ladage-van Doorn wrote: >> 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:amdatu-developers-bounces at amdatu.org] 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 > > _______________________________________________ > Amdatu-developers mailing list > Amdatu-developers at amdatu.org > http://lists.amdatu.org/mailman/listinfo/amdatu-developers _______________________________________________ Amdatu-developers mailing list Amdatu-developers at amdatu.org http://lists.amdatu.org/mailman/listinfo/amdatu-developers
