doc: adds documentation for explaining the code elements

doc/code_elements_header.md

@@ -0,0 +1,22 @@
+---
+title: Code elements
+tags: [meta-model]
+keywords: code, elements, ast, meta, model
+last_updated: October 1, 2015
+---
+
+Figure at the end of this page shows the meta model for Java executable code. 
+There are two main kinds of code elements. 
+First, statements `CtStatement` ([javadoc](http://spoon.gforge.inria.fr/mvnsites/spoon-core/apidocs/spoon/reflect/code/CtStatement.html)) 
+are untyped top-level instructions that can be used directly in a block of code. 
+Second, expressions `CtExpression` ([javadoc](http://spoon.gforge.inria.fr/mvnsites/spoon-core/apidocs/spoon/reflect/code/CtExpression.html)) 
+are used inside the statements. For instance, a `CtLoop` ([javadoc](http://spoon.gforge.inria.fr/mvnsites/spoon-core/apidocs/spoon/reflect/code/CtLoop.html)) 
+(which is a statement) points to `CtExpression` which expresses its boolean condition.
+
+Some code elements such as invocations and assignments are both statements 
+and expressions (multiple inheritance links). Concretely, this is translated as an 
+interface `CtInvocation` ([javadoc](http://spoon.gforge.inria.fr/mvnsites/spoon-core/apidocs/spoon/reflect/code/CtInvocation.html)) 
+inheriting from both interfaces `CtStatement` and `CtExpression`. 
+The generic type of `CtExpression` is used to add static type-checking when transforming programs.
+
+![Code part of the Spoon Java 8 metamodel]({{ "/images/code-elements.png" | prepend: site.baseurl }})

src/main/java/spoon/reflect/code/CtArrayRead.java

@@ -20,7 +20,12 @@
  * This code element defines an read access to an array.
  *
  * In Java, it is a usage of a array outside an assignment. For example,
- * <code>System.out.println(array[0]);</code>
+ * <pre>
+ *     int[] array = new int[10];
+ *     System.out.println(
+ *     array[0] // <-- array read
+ *     );
+ * </pre>
  *
  * If you process this element, keep in mind that you will process array[0]++ too.
  *

src/main/java/spoon/reflect/code/CtArrayWrite.java

@@ -23,8 +23,9 @@
  *
  * For example:
  * <pre>
+ *     Object[] array = new Object[10];
+ *     // array write
  *     array[0] = "new value";
- *     array[0] += "";
  * </pre>
  *
  * If you process this element, keep in mind that you won't process array[0]++.

src/main/java/spoon/reflect/code/CtAssert.java

@@ -17,7 +17,8 @@
 package spoon.reflect.code;
 
 /**
- * This code element defines an <code>assert</code> clause.
+ * This code element defines an assert clause.
+ * Example: <pre>assert 1+1==2</pre>
  */
 public interface CtAssert<T> extends CtStatement {
 	/**

src/main/java/spoon/reflect/code/CtAssignment.java

@@ -19,6 +19,11 @@
 /**
  * This code element defines an assignment.
  *
+ * Example:
+ * <pre>
+ *     int x;
+ *     x = 4; // <-- an assignment
+ * </pre>
  * @param <T>
  * 		type of assigned expression
  * @param <A>

src/main/java/spoon/reflect/code/CtBinaryOperator.java

@@ -19,6 +19,11 @@
 /**
  * This interface defines a binary operator.
  *
+ * Example:
+ * <pre>
+ *     // 3+4 is the binary expression
+ *     int x = 3 + 4;
+ * </pre>
  * @param <T>
  * 		Type of this expression
  */

src/main/java/spoon/reflect/code/CtBlock.java

@@ -21,9 +21,17 @@
 
 /**
  * This code element represents a block of code, that is to say a list of
- * statements enclosed in curly brackets. When the context calls for a return
+ * statements enclosed in curly brackets.
+ *
+ * Example: <pre>
+ *  { // <-- block start
+ *   System.out.println("foo");
+ *  }
+ *	</pre>
+ *
+ * When the context calls for a return
  * value, the block should contain a return statement as a lastly reachable
- * statement. The returned type if any is given by <code>R</code>.
+ * statement. The returned type if any is given by R.
  */
 public interface CtBlock<R> extends CtStatement, CtStatementList, TemplateParameter<R> {
 

src/main/java/spoon/reflect/code/CtBreak.java

@@ -17,7 +17,15 @@
 package spoon.reflect.code;
 
 /**
- * This code element defines a <code>break</code> statement.
+ * This code element defines a break statement.
+ * Example:
+ * <pre>
+ *     for(int i=0; i<10; i++) {
+ *         if (i>3) {
+ *				break; // <-- break statement
+ *         }
+ *     }
+ * </pre>
  */
 public interface CtBreak extends CtCFlowBreak {
 	/**

src/main/java/spoon/reflect/code/CtCase.java

@@ -17,7 +17,14 @@
 package spoon.reflect.code;
 
 /**
- * This code element defines a <code>case</code> within a <code>switch</code>.
+ * This code element defines a case within a switch-case.
+ *
+ * Example: <pre>
+ * int x = 0;
+ * switch(x) {
+ *     case 1: // <-- case statement
+ *       System.out.println("foo");
+ * }</pre>
  *
  * @param <S>
  * 		This type must be assignable from the switch type

src/main/java/spoon/reflect/code/CtComment.java

@@ -19,6 +19,11 @@
 /**
  * This code element defines a comment
  *
+ * Example:
+ * <code>
+ * int x = 0;
+ * // a comment
+ * </code>
  */
 public interface CtComment extends CtStatement {
 	enum CommentType {

src/main/java/spoon/reflect/code/CtConditional.java

@@ -17,7 +17,14 @@
 package spoon.reflect.code;
 
 /**
- * This code element defines conditional expressions using the ?.
+ * This code element defines conditional expressions using the ? (ternary expressions).
+ *
+ * Example:
+ * <pre>
+ *     System.out.println(
+ *        1==0 ? "foo" : "bar" // <-- ternary conditional
+ *     );
+ * </pre>
  */
 public interface CtConditional<T> extends CtExpression<T> {
 

src/main/java/spoon/reflect/code/CtConstructorCall.java

@@ -25,6 +25,9 @@
 /**
  * This code element represents a constructor call.
  *
+ * Example:<pre>
+ *     new Object();
+ * </pre>
  * @param <T>
  * 		created type
  */

src/main/java/spoon/reflect/code/CtContinue.java

@@ -17,7 +17,15 @@
 package spoon.reflect.code;
 
 /**
- * This code element defines the <code>continue</code> statement.
+ * This code element defines the continue statement.
+ * Example:
+ * <pre>
+ *     for(int i=0; i<10; i++) {
+ *         if (i>3) {
+ *				continue; // <-- continue statement
+ *         }
+ *     }
+ * </pre>
  */
 public interface CtContinue extends CtCFlowBreak {
 	/**

src/main/java/spoon/reflect/code/CtDo.java

@@ -18,6 +18,15 @@
 
 /**
  * This code element defines a <code>do</code> loop.
+ *
+ * Example:
+ * <pre>
+ *     int x = 0;
+ *     do {
+ *         x=x+1;
+ *     } while (x<10);
+ * </pre>
+ *
  */
 public interface CtDo extends CtLoop {
 	/**

src/main/java/spoon/reflect/code/CtExecutableReferenceExpression.java

@@ -21,7 +21,11 @@
 /**
  * This abstract code element defines an expression which represents an executable reference.
  *
- * In Java, it is generally of the form: <code>Type::method</code>.
+ * * Example:
+ * <pre>
+ *     java.util.function.Supplier p =
+ *       Object::new;
+ * </pre>
  *
  * @param <T>
  * 		Each executable references are typed by an interface with one method. This generic type

src/main/java/spoon/reflect/code/CtFieldRead.java

@@ -20,7 +20,11 @@
  * This code element defines an read access to a field.
  *
  * In Java, it is a usage of a field outside an assignment. For example,
- * <code>System.out.println(this.field);</code>
+ * <pre>
+ *     class Foo { int field; }
+ *     Foo x = new Foo();
+ *     System.out.println(x.field);
+ * </pre>
  *
  * If you process this element, keep in mind that you will process field++ too.
  *

src/main/java/spoon/reflect/code/CtFieldWrite.java

@@ -23,8 +23,9 @@
  *
  * For example:
  * <pre>
- *     this.field = "new value";
- *     this.field += "";
+ *     class Foo { int field; }
+ *     Foo x = new Foo();
+ *     x.field = 0;
  * </pre>
  *
  * If you process this element, keep in mind that you won't process field++.

src/main/java/spoon/reflect/code/CtFor.java

@@ -19,7 +19,14 @@
 import java.util.List;
 
 /**
- * This code element defines a <code>for</code> loop.
+ * This code element defines a for loop.
+ * Example:
+ * <pre>
+ *     // a for statement
+ *     for(int i=0; i<10; i++) {
+ *     	System.out.println("foo");
+ *     }
+ * </pre>
  */
 public interface CtFor extends CtLoop {
 

src/main/java/spoon/reflect/code/CtForEach.java

@@ -17,8 +17,14 @@
 package spoon.reflect.code;
 
 /**
- * This code element defines a <code>foreach</code> loop (enhanced
- * <code>for</code>).
+ * This code element defines a foreach statement.
+ * Example:
+ * <pre>
+ *     java.util.List l = new java.util.ArrayList();
+ *     for(Object o : l) { // <-- foreach loop
+ *     	System.out.println(o);
+ *     }
+ * </pre>
  */
 public interface CtForEach extends CtLoop {
 	/**

src/main/java/spoon/reflect/code/CtIf.java

@@ -20,6 +20,14 @@
 
 /**
  * This code element represents an <code>if</code> statement.
+ * Example:
+ * <pre>
+ *     if (1==0) {
+ *     	System.out.println("foo");
+ *     } else {
+ *     	System.out.println("bar");
+ *     }
+ * </pre>
  */
 public interface CtIf extends CtStatement, TemplateParameter<Void> {
 

src/main/java/spoon/reflect/code/CtInvocation.java

@@ -25,6 +25,13 @@
 /**
  * This code element defines a concrete invocation.
  *
+ * Example:
+ * <pre>
+ *     // invocation of method println
+ *     // the target is "System.out"
+ *     System.out.println("foo");
+ * </pre>
+ *
  * @param <T>
  * 		Return type of this invocation
  */

src/main/java/spoon/reflect/code/CtLambda.java

@@ -23,6 +23,13 @@
  * can have two sorts of body : an simple expression or a block of
  * statements. The usage of this concept in this class is:
  *
+ * <pre>
+ *     java.util.List l = new java.util.ArrayList();
+ *     l.stream().map(
+ *       x -> { return x.toString(); } // a lambda
+ *     );
+ * </pre>
+ *
  * <ul>
  * <li>
  * If your lambda has an expression, getBody method will

src/main/java/spoon/reflect/code/CtLiteral.java

@@ -19,7 +19,10 @@
 /**
  * This code element defines a literal value (an int, a string, etc).
  *
- * A null literal, as in "s = null", is represented by a CtLiteral whose value is null.
+ * <pre>
+ *     int x = 4; // 4 is a literal
+ * </pre>
+ * A null literal, as in s = null", is represented by a CtLiteral whose value is null.
  *
  * @param <T>
  * 		type of literal's value

src/main/java/spoon/reflect/code/CtLocalVariable.java

@@ -23,6 +23,12 @@
  * This code element defines a local variable definition (within an executable
  * body).
  *
+ * Example:
+ * <pre>
+ *     // defines a local variable x
+ *     int x = 0;
+ * </pre>
+ *
  * @param <T>
  * 		type of the variable
  * @see spoon.reflect.declaration.CtExecutable

src/main/java/spoon/reflect/code/CtNewArray.java

@@ -19,8 +19,13 @@
 import java.util.List;
 
 /**
- * This code element defines the creation of a new array.
+ * This code element defines the inline creation of a new array.
  *
+ * Example:
+ * <pre>
+ *     // inline creation of array content
+ *     int[] x = new int[] { 0, 1, 42}
+ * </pre>
  * @param <T>
  * 		type of this array (should be a array...)
  */

src/main/java/spoon/reflect/code/CtNewClass.java

@@ -26,6 +26,16 @@
 /**
  * This code element represents the creation of a anonymous class.
  *
+* Example:
+ * <pre>
+ *    // an anonymous class creation
+ *    Runnable r = new Runnable() {
+ *     	@Override
+ *     	public void run() {
+ *     	  System.out.println("foo");
+ *     	}
+ *    };
+ * </pre>
  * @param <T>
  * 		created type
  */

src/main/java/spoon/reflect/code/CtOperatorAssignment.java

@@ -18,6 +18,13 @@
 
 /**
  * This code element defines an self-operated assignment such as += or *=.
+ *
+ * Example:
+ * <pre>
+ *     int x = 0;
+ *     x *= 3; // <-- a CtOperatorAssignment
+ * </pre>
+ *
  */
 public interface CtOperatorAssignment<T, A extends T> extends CtAssignment<T, A> {
 	/**