diff options
Diffstat (limited to 'aspectj-attic/ajdoc-src/devnotes.txt')
| -rw-r--r-- | aspectj-attic/ajdoc-src/devnotes.txt | 98 |
1 files changed, 98 insertions, 0 deletions
diff --git a/aspectj-attic/ajdoc-src/devnotes.txt b/aspectj-attic/ajdoc-src/devnotes.txt new file mode 100644 index 000000000..5958dfbc2 --- /dev/null +++ b/aspectj-attic/ajdoc-src/devnotes.txt @@ -0,0 +1,98 @@ + +-------------- 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 + + + |