I've added a reporting section to the top level build, so that I could add a custom javadoc tag "tuscany.extension.spi" [1]. I used this tag because there are more than one type of spi in the code (witness core.spi)
I had to tweak the maxmemory of the maven javadoc plugin in order for mvn javadoc:aggregate to work from the modules directory. The output of this can be seen at [2] . Of note is the ImplementationImpl class documentation, which uses the custom javadoc tag at the class level. I think it is good to distinguish between tuscany code that is intended for use by extension or by calling methods direct. So far I've just added a comment in this example to say that the extension developer would be expected to derive from this class. I'm not sure if I'm happy with simply applying a documentation convention -- still thinking about it -- comments welcome. Kelvin. [1] http://svn.apache.org/viewvc?rev=934365&view=rev [2] http://people.apache.org/~kelvingoodson/SCA2.x/jdoc/ On Tue, Apr 13, 2010 at 5:18 PM, kelvin goodson <[email protected]> wrote: > Having gone through and familiarised myself with all the project level > dependencies for the SCA extension types (results will be posted when > apache infrastructure is responding again) , I'd like to consider how > we'd like to define and record our SPIs. > > I found someone considering the issue at [1]. He suggests a > @<projectname>.spi javadoc tag. He also suggests making the spi > evident via the package name, which may be something we might consider > after an initial definition phase. > > I propose that we start to use a javadoc tag of @tuscany.spi to > explicitly declare interfaces as spi-s. > > I recall being able to add javadoc at the package level, so a first > pass might be to add package level documentation using the tag. > Presence of the tag at this level would initially only give an > indication that there exist some methods in some classes within the > package that are SPIs. The exercise would then be to drill down and > complete the labeling/documentation to the method level. > > thoughts? > > Kelvin. > > [1] http://wiki.eclipse.org/SPI_description > > On Thu, Mar 11, 2010 at 6:45 PM, Raymond Feng <[email protected]> wrote: >> FYI: There is an maven eclipse plugin that can be used to generate maven >> dependency graph. >> >> http://m2eclipse.sonatype.org/ >> >> Thanks, >> Raymond >> >> -------------------------------------------------- >> From: "kelvin goodson" <[email protected]> >> Sent: Thursday, March 11, 2010 9:22 AM >> To: <[email protected]> >> Subject: Re: [2.x] SPI documentation, testing and tracking >> >>> I started investigating the dependencies of the binding modules, as a >>> starty in breaking this down and understanding the bigger picture. I >>> put a graph of this on the wiki [1] -- I plan to do the same for the >>> other extension types. >>> >>> [1] >>> http://cwiki.apache.org/confluence/display/TUSCANYWIKI/Tuscany+SPI+Investigations >>> >>> On Wed, Mar 10, 2010 at 3:56 PM, Simon Laws <[email protected]> >>> wrote: >>>> >>>> On Wed, Mar 10, 2010 at 1:53 PM, kelvin goodson <[email protected]> >>>> wrote: >>>>> >>>>> There's a first output from my endeavours at [1] >>>>> >>>>> I haven't checked the output, but how does this generally fit the bill? >>>>> >>>>> Kelvin >>>>> >>>>> [1] http://people.apache.org/~kelvingoodson/digests/out.xml >>>>> >>>> >>>> Nice. As a short term measure we can tell which code has changed >>>> easily without having to revert to looking up each file in the svn >>>> log. We need to filter it down a bit though. >>>> >>>> What we do need to do is be more precise about what we mean about SPI. >>>> Probably down to the level of classes we expect people to extend vs >>>> classes we expect people to call. >>>> >>>> A way of attacking this would be to take each of the extension types in >>>> turn; >>>> >>>> SCA specific ones >>>> -------------------------- >>>> binding >>>> implementation >>>> interface >>>> policy >>>> >>>> Tuscany runtime specific ones >>>> --------------------------------------------- >>>> databinding >>>> contribution >>>> host >>>> monitor >>>> extensibility >>>> endpointregistry >>>> etc. >>>> >>>> And look at which SPI like classes are used in each case. Then rather >>>> than just having a long list of SPI packages/classes which is >>>> difficult to understand at least we could identify those used when >>>> creating a particular extension type. >>>> >>>> So, for example, we could take a binding like binding.ws (it's >>>> relatively interesting) and look at it's dependencies. Obviously there >>>> are dependencies between the modules starting binding-ws-xxx however >>>> we are interested in the other, non-atom, Tuscany dependencies. We can >>>> ignore all the 3rd party and test dependencies. So the list I see for >>>> binding-ws (produced with mvn dependency:tree) is >>>> >>>> [INFO] org.apache.tuscany.sca:tuscany-binding-ws:jar:2.0-SNAPSHOT >>>> [INFO] +- >>>> org.apache.tuscany.sca:tuscany-contribution:jar:2.0-SNAPSHOT:compile >>>> [INFO] | +- >>>> org.apache.tuscany.sca:tuscany-assembly:jar:2.0-SNAPSHOT:compile >>>> [INFO] | | \- >>>> org.apache.tuscany.sca:tuscany-monitor:jar:2.0-SNAPSHOT:compile >>>> [INFO] | +- >>>> org.apache.tuscany.sca:tuscany-assembly-xsd:jar:2.0-SNAPSHOT:compil >>>> e >>>> [INFO] | +- >>>> org.apache.tuscany.sca:tuscany-extensibility:jar:2.0-SNAPSHOT:compi >>>> le >>>> [INFO] | +- >>>> org.apache.tuscany.sca:tuscany-common-xml:jar:2.0-SNAPSHOT:compile >>>> [INFO] | \- >>>> org.apache.tuscany.sca:tuscany-common-java:jar:2.0-SNAPSHOT:compile >>>> >>>> [INFO] | \- >>>> org.apache.tuscany.sca:tuscany-sca-api:jar:2.0-SNAPSHOT:compile >>>> [INFO] +- >>>> org.apache.tuscany.sca:tuscany-assembly-xml:jar:2.0-SNAPSHOT:compile >>>> [INFO] | +- >>>> org.apache.geronimo.specs:geronimo-stax-api_1.0_spec:jar:1.0.1:comp >>>> ile >>>> [INFO] | \- org.codehaus.woodstox:wstx-asl:jar:3.2.4:runtime >>>> [INFO] +- >>>> org.apache.tuscany.sca:tuscany-interface-wsdl:jar:2.0-SNAPSHOT:compile >>>> >>>> [INFO] | +- org.apache.tuscany.sca:tuscany-xsd:jar:2.0-SNAPSHOT:compile >>>> [INFO] | \- org.apache.ws.commons.schema:XmlSchema:jar:1.4.3:compile >>>> [INFO] +- wsdl4j:wsdl4j:jar:1.6.2:compile >>>> [INFO] +- org.apache.tuscany.sca:tuscany-builder:jar:2.0-SNAPSHOT:test >>>> [INFO] +- org.apache.tuscany.sca:tuscany-core:jar:2.0-SNAPSHOT:test >>>> [INFO] | +- >>>> org.apache.tuscany.sca:tuscany-core-spi:jar:2.0-SNAPSHOT:test >>>> [INFO] | +- >>>> org.apache.tuscany.sca:tuscany-interface-java:jar:2.0-SNAPSHOT:test >>>> >>>> [INFO] | +- cglib:cglib:jar:2.2:test >>>> [INFO] | \- asm:asm:jar:3.1:test >>>> [INFO] +- >>>> org.apache.tuscany.sca:tuscany-binding-sca-runtime:jar:2.0-SNAPSHOT:te >>>> st >>>> [INFO] | \- >>>> org.apache.tuscany.sca:tuscany-databinding:jar:2.0-SNAPSHOT:test >>>> [INFO] \- junit:junit:jar:4.8.1:test >>>> >>>> Extracting the real dependencies gives >>>> >>>> tuscany-contribution - processor and resolver base classes >>>> tuscany-assembly - assembly models >>>> tuscany-monitor - error reporting >>>> tuscany-assembly-xsd - model schema (don't know why it needs this here) >>>> tuscany-extensibility - locating extension points >>>> tuscany-common-xml - xml utilities >>>> tuscany-common-java - java utilities >>>> tuscany-sca-api - the SCA api (don't know why it needs this here, >>>> possibly for annotations) >>>> tuscany-assembly-xml - processor base classes >>>> tuscany-interface-wsdl - models WSDL interfaces >>>> tuscany-xsd - models schema >>>> >>>> If you look across the bindings it would be nice to think a pattern >>>> emerges. >>>> >>>> Ultimately we'll end up with a list again of course but well be able >>>> to add more detail about what each of the SPIs is for. >>>> >>>> Simon >>>> >> >
