Aspect-Oriented Generation of the API Documentation for AspectJ

1. Aspect-Oriented Generation of the API Documentation for AspectJ Michihiro Horie, Shigeru Chiba Tokyo Institute of Technology, Japan

2. API (Application Programming Interface) document • Writing API documents is a significant part of software development • In a framework/library, the documents are read by • user programmers • published API documents • developers • API documents including private members • In general, documentation tools can be used • javadoc, ajdoc etc.

3. Javadoc tool • The API document is written as doc comments. • Javadoc generates the API documentation in HTML. class Stack { : /** Looks at the object at the top of this * stack without removing it from the stack. * @exception EmptyStackException * if this stack is empty. */ Object peek() { if (size () == 0) throw new EmptyStackException(); return elementAt(size() – 1); }} an API document (.html)

4. Frameworks / libraries implemented in AspectJ • Internally-used aspects • never exposed to the users of these frameworks/libraries • transaction, exception handling, logging etc. • Modular implementations by classes and aspects • Doc comments are divided into many smaller modules

5. Problem:difficulty to understand the API document public class Stack { : /** Looks at the object at the * top of this stack .. */ Object peek() { return elementAt(size() – 1); }} Stack class ajdoc aspect StackChecking { /** @exception EmptyStackException .. */ before() : execution(Object Stack.peek()) { if (size () == 0) throw new EmptyStackException(); }} StackChecking aspect

6. CommentWeaver : a new documentation system for AspectJ • AOP for documentation • Joinpoints, pointcuts, advices • CW weaves the doc comments from classes and aspects when it writes out the HTML. • Domain-Specific Language • CW provides special tags for controlling the weaving

7. The woven doc comment class Stack { : /** Looks at the object at the * top of this stack .. */ Object peek() { return elementAt(size() – 1); }} Stack class CommentWeaver aspect StackChecking { /** @exception EmptyStackException .. */ before() : execution(Object Stack.peek()) { if (size () == 0) throw new EmptyStackException(); }}

8. Join points for doc comments • when the description of a class / field / method is written out • An AOP system explained by the ABX model A: a set of doc comments written in classesB: a set of doc comments written in aspectsX: the generation of the API document A × B → X [Masuhara et al.‘03]

9. Pointcuts and advicesfor doc comments • Pointcuts • A set of join points for doc comments • Implicit pointcut • Explicit pointcut • Advices • The text of doc comments • Standard javadoc tags • @exception, @return etc.

10. Implicit pointcut (1/2) • It selects the execution point when CW writes out the description of peek. class Stack { : /** Looks at the object .. */ Object peek() { return elementAt(size() – 1); }} /** @exception EmptyStackException * if this stack is empty */ before() : execution(Object Stack.peek()) { if (size () == 0) throw new EmptyStackException(); } A correct API document

11. Implicit pointcut (2/2) /** … */ execution(void B.var()) /** … */ call(void B.var()) class A { /** … */ void foo () { B.var(); } } class B { /** … */ static void bar() { … } } • It selects the each execution points. • call pointcut :caller methods (foo) • execution pointcut :the methods selected by execution (bar) • get,setpointcut :the methods accessing the fields

12. Explicit pointcut • Developers can explicitly specify pointcuts for doc comments • caller methods in the call chain (pop) class Stack { : /** Removes the object at the * top of .. */ Object pop() { Object obj = peek(); : } /** Looks at the object .. */ Object peek() { return elementAt(size() – 1); }} aspect StackChecking { /** @caller() 　* @exception EmptyStackException * it this stack is empty */ before() : execution(Object Stack.peek()) { if (size () == 0) throw new EmptyStackException(); }}

13. Multiple doc comments for one advice • a doc comment for the methods selected by @caller and one for the methods by @callee aspect StackChecking { /** * @exception EmptyStackException if the stack is empty * * @callee() * @exception EmptyStackException * if the stack is empty and if the caller classes * are in <tt>java.util</tt> package. */ before(Stack s) : call(Object Stack.peek()) && within(java.util.*) && target(s){ if (s.size () == 0) throw new EmptyStackException(); }}

14. Combining doc comments • To improve modularity, CW allows doc comments for named pointcuts. aspect StackChecking { /** * @caller() * @callee() * and if the caller is the classes in <tt>java.util</tt> package. */ pointcut checked(Stack s) : call(Object Stack.peek()) && within(java.util.*) && target(s); /**@exception EmptyStackException if this stack is empty. */ before(Stack s) : checked(s) { if (s.size () == 0) throw new EmptyStackException(); }}

15. Example: the observer pattern (1/2) public abstract aspect ObserverProtocol { : protected abstract pointcut subjectChange(Subject s); /** @include (updateObserver(Subject,Observer)) */ after(Subject s) : subjectChange(s) { Observer o = ...; updateObserver(s, o); } /** Defines how each <i>Observer</i> is to be * updated when a change to a <i>Subject</i> occurs. */ protected abstract void updateObserver(Subject subject, Observer observer); }}

16. Example: the observer pattern (2/2) aspect UpdateObserver extends ObserverProtocol { declare parents: Shape implements Subject; declare parents: Display implements Observer; : /** @caller(within(Shape+)) */ protected pointcut subjectChange(Subject s): (execution(void Point.set*(..)) || (execution(void Line.set*(..))) && this(s); /** @include (super.updateObserver(Subject, Observer)) * @include (Display.update()) */ protected void updateObserver(Subject subject, Observer observer) { ((Display) observer).update(); }}

17. Related work • Ajdoc • A documentation tool for AspectJ • The generated API document is not satisfactory. • The structure of doc comment is the same as the program structure.

18. Conclusion and future work • AOP for documentation • Join points, pointcuts, advices • CW weaves the doc comments from classes and aspects before it writes out the HTML. • Domain-Specific Language • Future work • Case study

19. A naive solution /** Look at the object … */ /** @exception EmptyStackException */ • Writring the effects of aspects together within the doc comments for the classes This breaks the maintainability of the aspects • Developers must update the doc commentswhenever the pointcut definitions are modified • Enumerating the affected methods is not a simple task.