Tool support for crosscutting concerns of API documentation Michihiro Horie, Shigeru Chiba Tokyo Institute of Technology, Japan
Feb 24, 2016
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