Community
Participate
Working Groups
Created attachment 110977 [details] An example of the readability problems. Build ID: I20080617-2000 Steps To Reproduce: 1. Load a project with a pointcut that advises a large number of methods (several hundred would do) 2. Run AJDoc 3. View the resulting page, see how the 'Advises:' text is not even on the screen for the majority of the links to the advised methods. More information: I propose two changes to fix the readability and usability of these AJDocs. First place the label for the AspectJ sections above the list (like standard Javadoc sections) to avoid the confusion that could be caused by the side label. Second strip the package from the links leaving only the class name and method name to reduce the clutter.
I agree...that is pretty nasty looking. I like your idea, but I am just concerned that not seeing the package can be disorienting. I think the package should go somewhere. Two suggestions: 1. separate sections for each group of advised locations by package. make the package name the header for the section. (would look nice in the example you show, but I am unsure how it would look for smaller examples) 2. use the title attribute in the <a> tag. Put the fully qualified name in the title. This way, the package would appear when hovered over.
Created attachment 111007 [details] The proposed changes for the advice detail section This png shows our proposed changes to the advises section. (The shown advice is on the constructor). We are also considering sorting the list alphabetically.
(In reply to comment #1) > I agree...that is pretty nasty looking. I like your idea, but I am just > concerned that not seeing the package can be disorienting. I think the package > should go somewhere. Two suggestions: > > 1. separate sections for each group of advised locations by package. make the > package name the header for the section. (would look nice in the example you > show, but I am unsure how it would look for smaller examples) > > 2. use the title attribute in the <a> tag. Put the fully qualified name in the > title. This way, the package would appear when hovered over. I like idea number 2. This would keep the layout short and give the information in a more obvious manner. (Right now you could see this in the status bar, but not at the cursor position) Another thing we are considering is moving the Aspect summaries to the top of the Aspect after any Aspect level javadocs to match the layout of normal javadocs. We would also like to move the 'Advises: ' part of the advice section to the end. Right now it comes before any comments on the advice.
There are some other formatting things we would like to change if we may. 1. There is an inconsistency in the naming of the headers. For declared annotations it is 'Annotated By:' and all the Inter-Type declarations have 'Declared By:' but for declare parents it says 'Aspect declarations:'. We would like to change 'Aspect declarations:' to 'Parents declared by:' or something else that is more consistent and less confusing. 2. We would like to change the links in the 'Annotated By:' and 'Parents declared by:' sections so that they are more readable and informative. For instance this is what it looks like for us now: 'com.cdmtech.icodes.item.subscription.aspects.SubscriptionAspect.declare @type: com.cdmtech.icodes.cargo.gentypes.Cargo : @Subscribable' We would like to change it to 'SubscriptionAspect : @Subscribable' and make the SubscriptionAspect link to the aspect page, and the @Subscribable link to the Subscribable annotation page. Similarly the declare parents would result in an 'AspectClassName : implements|extends InterfaceName' with corresponding links. The 'declare @type' and 'declare parents' are implied by the section, and the package would be placed in the link title so it could be viewed by hovering.
Created attachment 112275 [details] Patch with improved decorations
Created attachment 112359 [details] Update to patch fixing a problem with relative links.
Created attachment 118209 [details] Updated Fix Updated patch to work with changes to HtmlDecorator.java since the last patch I made.
unsetting the target field which is currently set for something already released
