| RE: [aspectj-dev] Planning for 1.1.1 and beyond - Call for help on 'ajdoc' like tool |
Sorry for the very slow reply. Tackling ajdoc would be a great contribution, as a number of us feel the need to get that tool back into the suite. There are two challenges to getting there. WHAT TO SHOW The tool needs to emulate javadoc for AspectJ sources, and also show the crosscutting structure. This means generating class-like documentation for aspects and AspectJ declarations (pointcuts, advice, and inter-type declarations). In addition we need to show the links for relationships between the AspectJ declarations and the Java declarations that they affect (e.g. method is advised by). The Abstract Structure Model (org.aspectj.asm) contains the AspectJ declaration hierarchy, including doc comments, and all of the crosscutting relationships. So it should give you access to all the data you need. I'm currently spec'ing out the 1.1 version of the model. I'd love ajdoc-specific comment when I send that out within the next week or so. However, making ajdoc work from the current model is the right way to start, and you can expect the ASM APIs not to change drastically. HOW TO SHOW IT This part is more challenging. We've tried a few approaches. The first was to dump the structure model as Java signatures with doc comments and IDs, let Javadoc run over those sources and generate the HTML, and then process the IDs in the HTML to rewrite AspectJ declarations and add the relationships. The last release of that was 0.8b4 (sources attached). The next approach was to add AspectJ-declaration handling to Javadoc (last released in 1.0.6, sources attached). This approach extends the JDK 1.3 Javadoc classes, and used the 1.0 compiler directly (it doesn't need to, since it can get the structure information from org.aspectj.asm). We also had an unreleased variant of this approach that used aspects to advise the AspectJ-specific behavior into javadoc. PLANNING FOR AJDOC 1.1 I think that the best place to pick up planning ajdoc is to figure out the right approach to extending or sidestepping Javadoc. One of the three approaches above could be adapted, each with different tradeoffs. XDoclet has been proposed. Javadoc'ing to XML and then XSLT'ing the AspectJ stuff in has also been suggested. It would be great if you sent out ideas for how you would like the implementation to work that we could comment on. We will also be happy support your implementation efforts. Cheers, Mik -- http://kerstens.org/mik > -----Original Message----- > From: aspectj-dev-admin@xxxxxxxxxxx [mailto:aspectj-dev-admin@xxxxxxxxxxx] > On Behalf Of Russell Miles > Sent: Friday, July 11, 2003 2:03 AM > To: aspectj-dev@xxxxxxxxxxx > > Hi everyone, > > I am trying to compile a list of requirements for an ajdoc like tool. > However I'm very new to this and am looking for a little help in getting > started. Is there an existing list of what the old ajdoc can do ? I've > used the tool but my only personal requirement at the moment is to get it > working for jdk 1.4.1 but Wes has already mentioned that hacking what is > existing to work is not the best way to go, and besides I was kinda hoping > it would be fun to work on this in a more open forum than just considering > my own needs ;o) > > So is anyone interested in coming up with a wish list for an ajdoc like > tool, or any technical advice on what may already exist that can be used > to give us a foundation. I am particularly interested in getting a common > core tool that can completely integrate with the future path of AspectJ > using any current features of Java 1.4.1 with an eye to the future 1.5, > and possibly integrated feature support for Eclipse - but yet again I'm > pretty new to these areas so am not sure what has already been done. > > I am hoping to post a wish list for feedback on this list as soon as I > can. Wes has already passed on some great suggestions for how to get > started but I am hoping the more experienced members of this community can > help a novice get started in contributing as actively as I can on this. > > Cheers, > > Russ Miles > > _______________________________________________ > aspectj-dev mailing list > aspectj-dev@xxxxxxxxxxx > http://dev.eclipse.org/mailman/listinfo/aspectj-dev
Attachment:
ajdoc-1.0.6-src.zip
Description: Zip compressed data
Attachment:
ajdoc-0.8b4-src.zip
Description: Zip compressed data