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.
Simon
--
Apache Tuscany committer: tuscany.apache.org
Co-author of a book about Tuscany and SCA: tuscanyinaction.com
