1. Tool support for crosscutting concerns of API documentation Michihiro Horie, Shigeru Chiba Tokyo Institute of Technology, Japan

2. 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)

3. Difficulty of modular description copy & paste@see tagideal Complete 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)

4. 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

5. 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

6. 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. */

7. @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. } */

8. 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 * java.lang.Class object. } * Do not override this method any more at … * @export : warning { * Warning: A Class object * returned by this method may not work …} */

9. Crosscutting caused by aspects Duplicated description  makeClass and makeInterface never throws RuntimeException ClassPool + makeClass() + makeInterface() : > 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. */

10. @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() : > 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 } */

11. 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(..))

12. 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) */

13. @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

14. 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

15. Javassist 9% violates procedure abstractions  22% reduction (LOC) All modularized number LOC crosscutting doc comments

16. Crosscutting along inheritance hierarchies in Javassist method namebehavior A note about the current implementation in the tangling text pruneDiscards unnecessary attributesA performance note defrostDefrosts the class so that it can be modified again A conflict with another function. makeNestedClassMakes a new public nested classA functional limitation getModifiersReturns the modifiers for the classClarifying ambiguity getClassFile2Returns a class file for this classInconsistency with the spec. Requires @liftup / @weave tag

17. 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 number

18. Eclipse 4% violates procedure abstractions  10% reduction (LOC) All modularized 107 violates inheritance hierarchies LOC number

19. 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 nameLOC # of advices (# of advised methods) needs doc comments original (LOC) AspectJ (LOC) call && within CtClassCaching30816 (18)002 FrozenChecking1113 (5)Yes312 ModifyChecking20614 (58)Yes2282 CodeAttributeCopy 572 (2)Yes33 ExistingTest741 (1)Yes22 InsertionHandling201 (2)Yes21 NotFoundExceptionHandling 322 (2)Yes22 ProxyFactorySynchronization 131 (1)001

20. 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]

21. 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