org.aspectj/aspectj-attic/ajdoc-src/devnotes.txt

-------------- Problems:

---- todo FIX output HTML is using "introduction" as labels.
- use "[Summary|Details] of [fields|methods|constructors] declared for target types"
  ("target" rather than "other" since they may be defined on self?)
- see also top index links:
  - super introductions...

solution: change doclet resources

---- FIXED comments not displayed for inter-type declarations in the aspects
solution:  IntroducedDocImpl.java sets source location for the dec from the introduced dec

>         dec.setSourceLocation(introducedDec.getSourceLocation()); // PR790, 712


---- PARTIAL FIX: synthetic constructors are shown in the javadoc
solution: post-process to remove unadvised constructors with same source location as parent class

See ClassDocImpl.java

problem with the solution: does not remove synthetic constructors on aspects??
 (only if they advise themselves?)


---- FIXED class cast exception trying to print introduced Constructor parameters
solution:
diff -r1.5 IntroducedDocImpl.java
105c107
<                             makeParameters(((MethodDocImpl)cs[i]).
---
>                             makeParameters(((ConstructorDocImpl)cs[i]).

---- introduced constructor names use the name of the declaring aspect, not the target 
solution:
diff -r1.4 ConstructorDocImpl.java
53c56,58
<         return containingClass().name();
---
>         String qname = getQualifiedName();
>         return (null != qname ? qname : containingClass().name());

---- ok: in aspect docs, inter-type declarations targeting the aspect work as expected,
     with both the inter-type declaration and the aspect-declared member documented.
     
---- ajc prints out declare-warnings when compiling for ajdoc

---- in aspect docs, links out to affected classes not printed for introduced constructors
essentially, the name of the constructor (should) differ for each target.  sigh.
- identifier should be the FQN of the aspect plus the type pattern and signature of the constructor.
  (parm signature - result, throws not required)
- display label in the aspect should be the identifier
  -> currently is the name of the aspect plus ()
- display label in affected classes should be the name of the affected class and the parm signature
  -> c

---- in target docs, links back to declaring aspects for introduced constructors fail
(iff parms?)

---- in target docs, summaries of members declared by aspects do not list initial comment line.

---- is aspect docs, members declared on target types are displayed only with the member name,
     not the typepattern.
see IntroducedDocImpl.java name()

    public String name() {
        // when using qualified name, unable to find links aout to targets
        // return (null != qualifiedName ? qualifiedName : dec().getId()); // XXX
        // when using id, only get simple name
        return dec().getId();
    }  
    ==> get caller to use printedName as label

UNFIXABLE - caller is sun doclet, and we only give it the member as parameter.
We do control the names of the links out, but not the name of the member in the class,
except to override qualifiedName, which causes the links out to fail (because
IntroducedDocImpl.createTargets() uses MemberDocImpl.weakEquals() to discover 
all introduced members in other types to find out if they were introduced by this
declaration (awful!), and [Method|Field|Member]DocImpl.weakEquals() implementations
use name() - using qualifiedName() would result in false positives for any field
in a target class). Overriding name() also causes other things to fail because it is 
used as an id.   Even changing the name during the lifecycle seems risky.  There's
not a clean separation between the type name and the name as displayed. 

---- in target class docs, introduced member links back to declaring aspect 
     have the member name as their label; should have the aspect type.
     
---- bad fix: references to declaration targets lost and incomplete html thereafter
     is a result of modifying name() or qualifiedName() of memberDoc

-------------- Background:
??
declaration target - Introduced
declaration source - Introduction