#29 Adding package-level JavaDocs, adding some overal architecture documentation to MappingProcessor

processor/src/main/java/org/mapstruct/ap/MappingProcessor.java

@@ -53,22 +53,33 @@ import org.mapstruct.ap.processor.ModelElementProcessor;
 import org.mapstruct.ap.processor.ModelElementProcessor.ProcessorContext;
 
 /**
- * A {@link Processor} which generates the implementations for mapper interfaces
+ * A JSR 269 annotation {@link Processor} which generates the implementations for mapper interfaces (interfaces
- * (interfaces annotated with {@code @Mapper}.
+ * annotated with {@code @Mapper}.
- * </p>
+ * <p>
  * Implementation notes:
- * </p>
+ * <p>
- * The generation happens by incrementally building up a model representation of
+ * The generation happens by incrementally building up a model representation of each mapper to be generated (a
- * each mapper to be generated (a {@link Mapper} object), which is then written
+ * {@link Mapper} object), which is then written into the resulting Java source file.
- * into the resulting Java source file using the FreeMarker template engine.
+ * <p>
- * </p>
+ * The model instantiation and processing happens in several phases/passes by applying a sequence of
- * The model instantiation and processing happens in several phases/passes by applying
+ * {@link ModelElementProcessor}s. The processors to apply are retrieved using the Java service loader mechanism and are
- * a sequence of {@link ModelElementProcessor}s.
+ * processed in order of their priority. The general processing flow is this:
- * </p>
+ * <ul>
+ * <li>retrieve mapping methods</li>
+ * <li>create the {@code Mapper} model</li>
+ * <li>perform enrichments and modifications (e.g. add annotations for dependency injection)</li>
+ * <li>if no error ocurred, write out the model into Java source files</li>
+ * </ul>
+ * <p>
  * For reading annotation attributes, prisms as generated with help of the <a
- * href="https://java.net/projects/hickory">Hickory</a> tool are used. These
+ * href="https://java.net/projects/hickory">Hickory</a> tool are used. These prisms allow a comfortable access to
- * prisms allow a comfortable access to annotations and their attributes without
+ * annotations and their attributes without depending on their class objects.
- * depending on their class objects.
+ * <p>
+ * The creation of Java source files is done using the <a href="http://freemarker.org/"> FreeMarker</a> template engine.
+ * Each node of the mapper model has a corresponding FreeMarker template file which provides the Java representation of
+ * that element and can include sub-elements via a custom FreeMarker directive. That way writing out a root node of the
+ * model ({@code Mapper}) will recursively include all contained sub-elements (such as its methods, their property
+ * mappings etc.).
  *
  * @author Gunnar Morling
  */

processor/src/main/java/org/mapstruct/ap/conversion/package-info.java

@@ -0,0 +1,26 @@
+/**
+ *  Copyright 2012-2013 Gunnar Morling (http://www.gunnarmorling.de/)
+ *  and/or other contributors as indicated by the @authors tag. See the
+ *  copyright.txt file in the distribution for a full listing of all
+ *  contributors.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+/**
+ * <p>
+ * Provides built-in conversions between primitive and wrapper types, strings, dates etc. Conversions are effectively
+ * short String snippets such as {@code (int)} or {@code .toString()} which are added inline to the generated mapping
+ * code.
+ * </p>
+ */
+package org.mapstruct.ap.conversion;

processor/src/main/java/org/mapstruct/ap/model/Type.java

@@ -127,6 +127,14 @@ public class Type extends AbstractModelElement implements Comparable<Type> {
         return isEnumType;
     }
 
+    /**
+     * Returns the implementation type to be instantiated in case this type is an interface iterable, collection or map
+     * type. The type will have the correct type arguments, so if this type e.g. represents {@code Set<String>}, the
+     * implementation type is {@code HashSet<String>}.
+     *
+     * @return The implementation type to be instantiated in case this type is an interface iterable, collection or map
+     *         type, {@code null} otherwise.
+     */
     public Type getImplementationType() {
         return implementationType;
     }

processor/src/main/java/org/mapstruct/ap/model/package-info.java

@@ -0,0 +1,25 @@
+/**
+ *  Copyright 2012-2013 Gunnar Morling (http://www.gunnarmorling.de/)
+ *  and/or other contributors as indicated by the @authors tag. See the
+ *  copyright.txt file in the distribution for a full listing of all
+ *  contributors.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+/**
+ * <p>
+ * Meta-model of mapper types, their methods, mappings between properties etc. Model elements can serialize themselves
+ * using FreeMarker templates.
+ * </p>
+ */
+package org.mapstruct.ap.model;

processor/src/main/java/org/mapstruct/ap/model/source/package-info.java

@@ -0,0 +1,25 @@
+/**
+ *  Copyright 2012-2013 Gunnar Morling (http://www.gunnarmorling.de/)
+ *  and/or other contributors as indicated by the @authors tag. See the
+ *  copyright.txt file in the distribution for a full listing of all
+ *  contributors.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+/**
+ * <p>
+ * Intermediary representation of mapping methods as retrieved from via the annotation processing API. The intermediary
+ * representation is then processed into the mapper model representation.
+ * </p>
+ */
+package org.mapstruct.ap.model.source;

processor/src/main/java/org/mapstruct/ap/package-info.java

@@ -19,7 +19,8 @@
 /**
  * <p>
  * This package and it sub-packages contain the implementation of the MapStruct annotation processor. Application code
- * using MapStruct should never work with these types directly.
+ * using MapStruct should never work with these types directly. Refer to the documentation of
+ * {@link org.mapstruct.ap.MappingProcessor} to learn more about the internal architecture of the processor.
  * </p>
  */
 package org.mapstruct.ap;

processor/src/main/java/org/mapstruct/ap/processor/package-info.java

@@ -0,0 +1,25 @@
+/**
+ *  Copyright 2012-2013 Gunnar Morling (http://www.gunnarmorling.de/)
+ *  and/or other contributors as indicated by the @authors tag. See the
+ *  copyright.txt file in the distribution for a full listing of all
+ *  contributors.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+/**
+ * <p>
+ * Contains model processors which perform tasks such as retrieving mapping methods, creating a model representation
+ * and writing the model into Java source files. Processors are invoked in order as per their priority value.
+ * </p>
+ */
+package org.mapstruct.ap.processor;

processor/src/main/java/org/mapstruct/ap/util/TypeFactory.java

@@ -133,7 +133,7 @@ public class TypeFactory {
         }
 
         DeclaredType declaredType = (DeclaredType) mirror;
-        ArrayList<Type> typeParameters = new ArrayList<Type>( declaredType.getTypeArguments().size() );
+        List<Type> typeParameters = new ArrayList<Type>( declaredType.getTypeArguments().size() );
 
         for ( TypeMirror typeParameter : declaredType.getTypeArguments() ) {
             typeParameters.add( getType( typeParameter ) );
@@ -151,7 +151,7 @@ public class TypeFactory {
                             primitiveType == double.class ? typeUtils.getPrimitiveType( TypeKind.DOUBLE ) :
                                 primitiveType == boolean.class ? typeUtils.getPrimitiveType( TypeKind.BOOLEAN ) :
                                     primitiveType == char.class ? typeUtils.getPrimitiveType( TypeKind.CHAR ) :
-                                        typeUtils.getPrimitiveType( TypeKind.BYTE );
+                                        typeUtils.getPrimitiveType( TypeKind.VOID );
     }
 
     private Type getImplementationType(TypeMirror mirror) {

processor/src/main/java/org/mapstruct/ap/util/package-info.java

@@ -0,0 +1,24 @@
+/**
+ *  Copyright 2012-2013 Gunnar Morling (http://www.gunnarmorling.de/)
+ *  and/or other contributors as indicated by the @authors tag. See the
+ *  copyright.txt file in the distribution for a full listing of all
+ *  contributors.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+/**
+ * <p>
+ * Several helper types dealing with collection types, option management etc.
+ * </p>
+ */
+package org.mapstruct.ap.util;

processor/src/main/java/org/mapstruct/ap/writer/package-info.java

@@ -0,0 +1,24 @@
+/**
+ *  Copyright 2012-2013 Gunnar Morling (http://www.gunnarmorling.de/)
+ *  and/or other contributors as indicated by the @authors tag. See the
+ *  copyright.txt file in the distribution for a full listing of all
+ *  contributors.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+/**
+ * <p>
+ * Infrastructure for dealing with the FreeMarker template engine.
+ * </p>
+ */
+package org.mapstruct.ap.writer;