On Thu, Apr 15, 2010 at 1:00 PM, Simon Laws <[email protected]> wrote: > On Thu, Apr 15, 2010 at 12:47 PM, kelvin goodson > <[email protected]> wrote: >> 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/ >> > > Looking good kelvin. A couple of things. > > We have > > Module > Package > Interface or Class > > I suspect that not all interfaces or classes in a package are SPIs. > Even after the various re-organizations there have been in 2.x. I may > be wrong but I'd continue adding the annotations at the > Class/Interface level and we'll have to do some analysis after the > first pass to see if anything needs to be moved. > > As for the annotation itself. My concern is whether we'll remember > what text can come after it. > > @tuscany.extension.spi By Inheritance > > I assume that you can put anything in place of "By Inheritance" and it > will be reproduced in the Javadoc. Maybe this is OK. However do the > annotations give us any extra facilities over and above being able to > grep for them in the code. If grep is the thing then we should > probably turn the "By Inheritance" part into part of the annotation.
thanks Simon, I took a little look around to see if there was some means of providing an enumerated set of variants of a given tag, but I can't find anything, so I guess the dot notation can be extended to include the means by which the spi programmer uses the code. We could have tuscany.spi.extension.(inherit | inheritfrom | specialize) and tuscany.spi.extension.(client | asclient) I think I favour tuscany.spi.extension.inheritfrom and tuscany.spi.extension.asclient, as it would seem less ambiguous to a novice tuscany extender. I note that I have naturally veered towards switching from tuscany.extension.spi.* to tuscany.spi.extension.* - and I think this lends itself better towards categorising other spis in the future. Kelvin. > > Simon > > -- > Apache Tuscany committer: tuscany.apache.org > Co-author of a book about Tuscany and SCA: tuscanyinaction.com >
