On Thu, Apr 15, 2010 at 1:38 PM, kelvin goodson <[email protected]> wrote: > 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 >> >
I may have missed this earlier in the thread but what are (inherit | inheritfrom | specialize) and (client | asclient) for? And do we really need that level of detail, i'd worry it would quite quickly get out of date. ...ant
