Transcript Tools for crosscutting concerns of API documentation

Tool support for
crosscutting concerns
of API documentation
Michihiro Horie, Shigeru Chiba
Tokyo 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
API documentation (.html)
Doc comment (.java)
/** Tests if this stack is empty
* @return true if and only if …
*/
public boolean empty() { … }
Javadoc
Difficulty of modular description
(copy & paste)
/** Writes a class file … on a local disk.
* Once this method is called, further
* modification are not possible any
* more. */
(@see tag)
/** Writes a class file … on a local disk.
* @see toBytecode(DataOutputStream)
*/
copy & paste
Complete API description
Duplication is avoided

void writeFile(String directoryName) {
:
DataOutputStream out = …;
toBytecode(out);
:
}
/** Converts this class to a class file.
* Once this method is called, further
* modification are not possible any
* more.
* …
*/
@see tag

ideal


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()
/** Writes a class file … in the current directory.
* Once this method is called, further modification
* are not possible any more.
*/
writeFile(String)
/** Writes a class file … on a local disk.
* Once this method is called, further modification
* are not possible any more.
*/
toBytecode(
DataOutputStream)
/** 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
/** @quote(toClass(CtClass,ClassLoader)).conversion
* This is only for backward compatibility.
* @quote(toClass(CtClass, ClassLoader)).warning */
toClass(ClassLoader)
toClass(CtClass, ClassLoader)
/**@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()
:
/** 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. */
<<aspect>>
FrozenChecking
before(ClassPool, String) :
execution(* makeClass())
|| execution(* makeInterface())
/** @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 …}
exec(* makeClass(..))
|| exec(* makeInterface(..))

JP_CALLER and JP_CALLEE
 Appends

text to the caller / callee methods
(ex.) @weave(JP || JP_CALLER) {…}
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()
:
/**
*
*
*
Defrosts the class so that the class can
be modified again.
If defrost will be called later, pruning
must be disallowed in advance.
*/
CtClassType
+ defrost()
:
/** (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()
:
/** Defrosts the class so that the class can
* be modified again.
*/
@liftup
=
CtClassType
+ defrost()
:
/** @weave(exec(void CtClass.defrost()) {
*
If defrost will be called later, pruning
*
must be disallowed in advance. } */
Case studies

We found many crosscutting concerns
in real API documentation
 Javassist

version 3.6
 Java

standard library
Java 6
 Eclipse

 An

Release 3.3
AspectJ version of Javassist
based on Javassist 3.6
Javassist
9% violates
procedure abstractions
 22%
number

reduction (LOC)
All modularized
LOC

crosscutting doc comments
Crosscutting along inheritance
hierarchies in Javassist

Requires @liftup / @weave tag
method name
behavior
A 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 A conflict with another
modified again
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.
The standard library of Java 6
20% violates procedure abstractions
 21%


number

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

Eclipse
4% violates procedure abstractions
 10%

All modularized
107 violates inheritance hierarchies
LOC

reduction (LOC)
number

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.
LOC
# of advices
(# of advised
methods)
CtClassCaching
308
16 (18)
FrozenChecking
111
3 (5)
Yes
3
1
2
ModifyChecking
206
14 (58)
Yes
22
8
2
CodeAttributeCopy
57
2 (2)
Yes
3
3
ExistingTest
74
1 (1)
Yes
2
2
InsertionHandling
20
1 (2)
Yes
2
1
NotFoundExceptionHandling
32
2 (2)
Yes
2
2
ProxyFactorySynchronization
13
1 (1)
0
0
aspect name
needs doc
comments
original
(LOC)
AspectJ
(LOC)
call
&&
within
0
0
2
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