[aspectj-dev] ajdoc lite

[Wes Isberg <wes@xxxxxxxxxxxxxx>]

I wonder if some of the demand now for ajdoc would 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.  Mik has already
provided some model-walking code that I will include in the
samples I post later, and we can answer questions on
aspectj-dev@xxxxxxxxxxx.  I believe a good Java programmer could
write the code to gather the data in 4-16 hours and build the
indexes in 3-6 times that initial effort.

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.

So:

- For those people for whom the lack of a documentation tool
  is a hindrance to adoption, does this partial solution help
  enough that it is worth doing?

- Who is interested in contributing to this effort?

Thanks -
Wes