Tool support for crosscutting concerns of API documentation

Michihiro Horie, Shigeru ChibaTokyo Institute of Technology, Japan

API (Application Programming Interface) documentation

A good library or framework has a good API documentation Documentation in a program source file

In Lisp, a function definition can include the description In Java, documentation is written as doc comment

Documentation tools

/** Tests if this stack is empty * @return true if and only if … */public boolean empty() { … }

Javadoc

Doc comment (.java)

API documentation (.html)

Difficulty of modular description

copy & paste @see tag idealComplete API description

Duplication is avoided

void writeFile(String directoryName) { : DataOutputStream out = …; toBytecode(out); :}

üü

/** Writes a class file … on a local disk. * @see toBytecode(DataOutputStream) */

(@see tag)

/** Converts this class to a class file. * Once this method is called, further * modification are not possible any * more. * … */

/** Writes a class file … on a local disk. * Once this method is called, further * modification are not possible any * more. */

(copy & paste)

üü

Another kind of crosscutting concern

Modular description for user programmers is incompatible with modular description for developers

Due to a mismatch between the two kinds of decompositions for Programming

Classes, methods, etc. API documentation

The behavior of publicly exposed members

CommentWeaver :a new documentation system Allows programmers to modularize crosscutting

concerns of API documentation Across procedure abstractions Along an inheritance hierarchy Caused by an aspect

An extended tool of Javadoc Provides special tags to control modularized text Supports Java and AspectJ

Crosscutting across procedure abstractions

Methods with the same name but different parameters Descriptions of them have some overlaps

Function about red comment is implemented in toBytecode

writeFile()

writeFile(String)

toBytecode( DataOutputStream)

/** Writes a class file … in the current directory. * Once this method is called, further modification * are not possible any more. */

/** Writes a class file … on a local disk. * Once this method is called, further modification * are not possible any more. */

/** Converts this class to a class file. * Once this method is called, further modification * are not possible any more. */

@quote tag

Refers to the doc comment of other methods @export tag is used to select which text

should be referred to For maintainability, text is only shared among methods in

the call chain.

writeFile()

writeFile(String)

toBytecode( DataOutputStream)

/** Writes a class file … in the current directory. * @quote(writeFile(String)) */

/** Writes a class file … on a local disk. * @export { * @quote(toBytecode(DataOutputStream)) } */

/** Converts this class to a class file. * @export { * Once this method is called, further modification * are not possible any more. } */

Multiple @export tags @export with a name

@quote tag refers to the name of @export

toClass(ClassLoader)

toClass(CtClass, ClassLoader)

/** @quote(toClass(CtClass,ClassLoader)).conversion * This is only for backward compatibility. * @quote(toClass(CtClass, ClassLoader)).warning */

/**@export : conversion { * Converts the class to a * <code>java.lang.Class</code> object. } * Do not override this method any more at … * @export : warning { * <p><b>Warning:</b> A Class object * returned by this method may not work …} */

Crosscutting caused by aspects

Duplicated description makeClass and makeInterface never throws

RuntimeException

ClassPool+ makeClass()+ makeInterface()

:

<<aspect>>FrozenChecking

before(ClassPool, String) : execution(* makeClass()) || execution(* makeInterface())

/** Creates a new public class… * @throws RuntimeException * if the existing class is frozen. */

/** Creates a new public interface… * @throws RuntimeException * if the existing class is frozen. */

/** @throws RuntimeException * if the existing class is frozen. */

@weave tag

Used to append the following text to methods selected by the argument Its argument is AspectJ-like pointcuts

call, exec, etc.

ClassPool+ makeClass()+ makeInterface()

:

<<aspect>>FrozenChecking

before(ClassPool, String) : execution(* makeClass()) || execution(* makeInterface(*))

/** Creates a new public class… */

/** Creates a new public interface… */

/**@weave(exec(* makeClass(..)) * || exec(*makeInterface(..))) { * @throws RuntimeException * if the existing class is frozen } */

Special values for @weave

JP Avoids the repetition of the AspectJ pointcut Represents join point shadow

cflow and if pointcuts are ignored (ex.) @weave(JP) {@throws RuntimeException …}

JP_CALLER and JP_CALLEE Appends text to the caller / callee methods

(ex.) @weave(JP || JP_CALLER) {…}

exec(* makeClass(..))|| exec(* makeInterface(..))

Crosscutting along an inheritance hierarchy

Public interfaces (or abstract classes) Actual implementations given by non-public classes

If non-public classes show implementation-dependent behavior,the description should be written in them, instead of public ones.

CtClass+ defrost()

:

CtClassType+ defrost()

:

/** Defrosts the class so that the class can * be modified again. * If defrost will be called later, pruning * must be disallowed in advance. */

/** Defrosts the class so that the class can * be modified again. * If defrost will be called later, pruning * must be disallowed in advance. */

/** (none) */

@weave tag for methods

Also available in the doc comment of methods @liftup tag can be used instead of @weave

Takes no argument

CtClass+ defrost()

:

CtClassType+ defrost()

:

/** Defrosts the class so that the class can * be modified again. */

/** @weave(exec(void CtClass.defrost()) { * If defrost will be called later, pruning * must be disallowed in advance. } */

=@liftup

Case studies

We found many crosscutting concerns in real API documentation Javassist

version 3.6 Java standard library

Java 6 Eclipse

Release 3.3 An AspectJ version of Javassist

based on Javassist 3.6

Javassist 9% violates

procedure abstractions 22% reduction (LOC)

All modularized

num

ber

LOC

crosscutting doc comments

Crosscutting along inheritance hierarchies in Javassist

method name behaviorA note about the current implementation in the tangling text

prune Discards unnecessary attributes A performance note

defrost Defrosts the class so that it can be modified again

A conflict with another function.

makeNestedClass Makes a new public nested class A functional limitation

getModifiers Returns the modifiers for the class Clarifying ambiguity

getClassFile2 Returns a class file for this class Inconsistency with the spec.

Requires @liftup / @weave tag

The standard library of Java 6

20% violates procedure abstractions 21% reduction (LOC)

All modularized We selected only the packages that contain more than 100

public methods and 1,000 LOC of doc comments Nothing violates inheritance hierarchies

LOC

num

ber

Eclipse

4% violates procedure abstractions 10% reduction (LOC)

All modularized 107 violates inheritance hierarchies

LOC

num

ber

An AspectJ version of Javassist

If an aspect implements a functional concern, that concern must be described in the API documentation of the advised classes.

aspect name LOC# of advices(# of advised

methods)

needs doc comments

original(LOC)

AspectJ(LOC)

call &&

withinCtClassCaching 308 16 (18) 0 0 2FrozenChecking 111 3 (5) Yes 3 1 2ModifyChecking 206 14 (58) Yes 22 8 2CodeAttributeCopy 57 2 (2) Yes 3 3ExistingTest 74 1 (1) Yes 2 2InsertionHandling 20 1 (2) Yes 2 1NotFoundExceptionHandling 32 2 (2) Yes 2 2ProxyFactorySynchronization 13 1 (1) 0 0 1

Related work Javadoc, Ajdoc The documentation of the CLOS Metaobject protocol

[Kiczales et.al. ’92] Verifying specification of class libraries

Design by contract [Meyer ’92] Typestate checking [Bierhoff et.al. ’07] FUSION [Jaspan et.al. ’09]

Literate programming [Knuth ’83] Approaches to understand crosscutting structures

Aspect-Aware Interface [Kiczales et.al. ‘05] Open Module [Aldrich ’05] XPI [Griswold et.al. ’06] Active model [Coelho et.al. ’06]

Concluding remarks

CommentWeaver Aspect-oriented simple extension to Javadoc Modular description of doc comments

Crosscutting concerns of API documentation Procedures, inheritances, and aspects

We found real examples Javassist Java standard library Eclipse framework AspectJ version of Javassist