RE: [aspectwerkz-dev] aw doc

Alex,

I agree that this is a feasible alternative.  With AspectJ 1.0 we had just
that working for ajdoc--extended/patched Javadoc classes caused the AspectJ
declarations to documented, and the links to be added while those were being
processed.  And we had a version of it working with AspectJ as the patching
mechanism, but didn't want our only example of AspectJ use at the time to be
patching.

The main problem we encountered is that this approach was dependent on JDK
versions.  So we forced people to use the 1.2 tools.jar when working on 1.3
and 1.4 because we didn't have the resources to update ajdoc or support
multiple JDKs.  So oddly enough it has turned out that the HTML sources have
been a more stable 'platform' than the Javadoc classes.

I recommend keeping in mind that this is a simple problem (i.e. only
involves new declaration entries and links) and doing the thing that will be
easiest to maintain.  But it's possible for the "patch" approach to be
cleaner overall, and it would be neat if you used AW to do it.  

Mik

> -----Original Message-----
> From: Alexandre Vasseur [mailto:[email protected]]
> Sent: Sunday, October 10, 2004 10:25 AM
> To: [email protected]
> Subject: [aspectwerkz-dev] aw doc
> 
> Hi
> 
> So to start discussing again about the "generate javadoc with advised
> by information etc".
> 
> I am not sure ajdoc is the way to go. It makes lot of assumption about
> how the javadoc looks like, and acts in two phases as it was described
> here in a previous post.
> Moreover, you cannot use it with custom doclet etc.
> 
> I am wondering, based on what I have found about "jdoc2", how
> difficult it would be instead to try to "patch" (see [1] below) the
> Sun javadoc classes, so that when the javadoc for a method gets
> generated, we simply query AW to see if we have an advice here (see
> [2] below).
> Ok, it sounds like a crazy idea ? Mh, more than patching generated html ?
> 
> So
> [1] could be achieved may be by applying some aspect to ajdoc itself
> (thus awdoc calls the Main class of javadoc with some awdoc aspects turned
> on)
> It needs some more digging
> [1] can be achieved by shipping a modified version of Sun javadoc.
> Since it is not allowed, we can ship a module that do the change for
> you (just as the hook does for hotspot java 1.3). In the long run, we
> can make use of Java 5 hotswap as well. But i think we should first to
> have the job done using our own food aka AW aspects !
> 
> [2] the question here is that if from a weaver perspective we can have
> all the info we want, it can be somehow more complex to make it
> available f.e. when you have call pointcuts, pointcut references,
> withincode(..) filter and runtime checks residual parts (f.e. cflow).
> 
> Side note: for Java 1.4 self defined aspect, we can hack ~5 doclet to
> embed the aspect def in the javadoc - but that s too easy to discuss
> it.
> 
> Thoughts ?
> 
> Alex