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 {
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 {
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 classes B: a set of doc comments written in aspects X: the generation of the API document
A × B → X
[Masuhara et al. ‘03]

9. Pointcuts and advices for doc comments
A set of join points for doc comments
Implicit pointcut
Explicit pointcut
Advices
The text of doc comments
Standard javadoc tags
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); }}
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) It selects the each execution points.
call pointcut : caller methods (foo)
execution pointcut : the methods selected by execution (bar)
get, set pointcut : the methods accessing the fields
/** … */
execution(void B.var())
/** … */
call(void B.var())
class A {
/** … */
void foo () {
B.var(); }
class B {
/** … */
static void
bar() { … } }

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 {
　* @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 and one for the methods
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 {
/**
* 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);
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);
(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; : */
protected pointcut subjectChange(Subject s):
(execution(void Point.set*(..)) || (execution(void Line.set*(..))) && this(s);
(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.
アドバイスの織り込み箇所　＝　コメントの追加箇所
仕様変更のときなどに private なメンバーの API を参照したりすると便利

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
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 comments whenever the pointcut definitions are modified
Enumerating the affected methods is not a simple task.
/** Look at the object … */
EmptyStackException */