Community
Participate
Working Groups
For tracking purposes, from the mail list: Some of the demand now for ajdoc could be satisfied in part by aspect indexes into javadoc HTML. The indexes would be HTML files generated into an existing set of javadoc HTML files and would have links for crosscutting structure: - a list of aspects and classes containing pointcuts - a list of their pointcuts, advice, and inter-type declarations - for pointcuts and advice, links to the javadoc for static shadow of the pointcuts (i.e., the methods advised by call or execution, etc.) - for inter-type declarations, links to the types that the members or supertypes are declared on - a reverse list, in package/type/member order of affected types and members, with links back to aspects advising them (i.e., for now back to the first list) - perhaps update the javadoc files for the affected types with a link back to their entry in the aspect index. A single link for each affected type would be great, and a link for each affected member might not be too difficult. It might be worth building a partial and interim solution because there is a lot of interest in something like ajdoc, but efforts are stymied in the short term by the desire to (and difficulty of) doing it right. This is a good project for a contributor interested in learning to build tools on AJDE. This index could be generated from data obtained by walking the structure model after a compile completes. The tool would generate the appropriate lists or tables with predicted links into corresponding javadoc. This proposal does not render javadoc for AspectJ source files and relies on javadoc to document the non-aspect sources, so it is not intended as a final solution for ajdoc. (However, the code might form the basis for something more than these simple indexes, depending on how it's built.) To avoid confusing people, we should call it something else -- mostly likely whatever name is proposed by the contributor who builds it. There is sample model-walking code in the CVS tree at docs/sandbox/api-clients.
User feedback at OOPSLA reinforced the importance of ajdoc to me, and I plan on addressing that over the next few weeks.
We all thought that we buried that version of ajdoc that generated source files, ran Javadoc over them, then post-processed the generated HTML. But this seemed like the only way to get ajdoc back in the hands of users given our current resources. So I resurrected it, moved it on top of the ASM, and made it work for 1.2-1.4 doclets. By "made it work", I mean that it generates documentation for spacewar and a few other simple systems in its test suite. I implemented the "advises" and "advised by" links, so there is still all the declare stuff to do. But now that all the infrastructure works that should be straightforward. Russell Miles has volunteered (yay!) and I'll help him make that work. A few notes: BUILD George: Could you check that the "ajdoc" module is getting built on the build machine? Also, it's "ajdoc.bat" file should be getting generated in the same way that "ajbrowser.bat" is. Wes: should George grab the script generation stuff from 1.0.x or should we just copy the ajbrowser stuff since its so similar? TESTING We need to run ajdoc on a big system as a part of testing, and make sure that it doesn't fail. Either the JDK or our source tree. Right now I'm pretty sure something will fail when it gets into the corner case of the JDK, but any fixes should be straightforward. How do we do that as a part of the build? It would also be good to run it with 1.2, 1.3, and 1.4 versions of Javadoc underneath. UI RATIONALE I took a quick pass at making the display of crosscutting a bit better. The "Advises" and "Advised by" headings show up in a light-orange cell (keeping with "blue is OO, orange is AO" theme). The shading parallels how Javadoc displays "inherited members"--i.e. things that aren't really in that file, but are links to elsewhere. Instead of a vertical arrangement of "inherited members", the table has a horizontal arrangement to make it different and make better use of h-space.
This is great to see. And interesting: generating Java stubs! It seems like this bug should stay open until the work of getting it to product is completed. That means something like: - build works in eclipse for everyone and Ant - [preferred?] put tools.jar in lib/jdk14/tools.jar - or use build variable for tools.jar - doc this in build readme], - build taskdef updated to handle variable for tools.jar - junit uses lib/junit/junit.jar - normal and release build scripts updated as needed [this is a condition for any checkin] - JUnit tests work like the others - AjdocModuleTests in default directory - invoked from run-all-junit-tests - invoked from Ant using tests/junit-modules.xml - tests run ok during normal and release build - rollout script no taskdef? - documented dev-guide doc index? release notes examples/build.xml? list of known limitations, in bug database or in dev-guide - usable: compiler, other errors reported correctly (e.g., if the compiler crashes you get a message saying to send the stack to support@aspectj.org) - (but live with System.out for now) - esp. checking for tools.jar and reporting when unavailable or the wrong version - tested: automated mechanism to - run against all our examples - in JDK 1.3, 1.4 - like you say, run against something big (jdk is too big) - verify the results
Thanks for the great task-list Wes. All of these items should now be addressed and ajdoc ready for people to try.
