ArchitecturalOverview

Overview

The main functionality of the documentation system in CLforJava is gained through the use of Annotations. Annotations were added to the Java platform as of 5.0. Annotations were chosen because they will allow one solution to handle both Java classes created by the compiler and the pre-existing Java classes necessary for the system to run.

As the compiler parses Lisp code and builds the Java classes it will use the information it gathers to construct annotations and add them to the classes. Once this process is complete an annotation processing tool will "pull out" all the annotations, build the appropriate XML files and store them as resources in JAR files. The alternate case is that the system is doing an in-memory compilation of some Lisp code.

Quoting from Sun's official site, "It (annotation-based development) lets us avoid writing boilerplate code under many circumstances by enabling tools to generate it from annotations in the source code. This leads to a declarative programming style where the programmer says what should be done and tools emit the code to do it."

Types to Document

• Symbol
• System Class
• Constant Variable
• Function
• Compiler-Macro
• Method-Combination
• Type
• Structure
• Variable
• Object

Annotation Class Design

We will be using Meta-Annotations for the documentation system. These "annotations of annotations" contain four types: Target, Retention, Documented, and Inherited.

Our target value will be ElementType.TYPE which means that it can be applied to any element of the class. This is necessary since the placement of the annotation will vary depending on the "thing" that is being documented.

Our retention policy will vary based upon the type of file we are working with. When compiling a Lisp file we will use RetentionPolicy.CLASS since the contents will already be stored in our external resource at runtime. In the case of an in-memory compilation we will use RetentionPolicy.RUNTIME.

The system will not be utilizing the @Documented annotation type. The system will use full annotations which simply means that our annotations will have multiple data members.

Questions:
1. Do we want our annotations to be included in JavaDocs? ? If so we will include @Documented in the annotation.
2. What happens when doing an in-memory compilation? Do we still get a class file?

References

Java Annotations
W3C XSL Transformations
W3C XML Schemas
XML DTD

-- IanJones - 21 Oct 2005