doc: Improve javadoc for CtTypeInformation and `CtCodeElement#parti…

…allyEvaluate` (#5331)

Co-authored-by: intrigus-lgtm <[email protected]>

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

@@ -17,9 +17,10 @@ public interface CtCodeElement extends CtElement {
 	/**
 	 * Partially evaluates an element and all its sub-elements.
 	 *
-	 * @param <R>
-	 * 		the returned element
-	 * @return the result of the partial evaluation
+	 * @param <R> the type of the returned element
+	 * @return the result of the partial evaluation.
+	 *         The element is always cloned, even if nothing has been evaluated.
+	 * @see spoon.support.reflect.eval.VisitorPartialEvaluator
 	 */
 	<R extends CtCodeElement> R partiallyEvaluate();
 

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

@@ -16,7 +16,7 @@
 import static spoon.reflect.path.CtRole.THEN;
 
 /**
- * This code element represents an <code>if</code> statement.
+ * This code element represents an {@code if} statement.
  * Example:
  * <pre>
  *     if (1==0) {
@@ -29,26 +29,57 @@
 public interface CtIf extends CtStatement, TemplateParameter<Void> {
 
 	/**
-	 * Gets the boolean expression that represents the <code>if</code>'s
+	 * Gets the boolean expression that represents the {@code if}'s
 	 * condition.
 	 */
 	@PropertyGetter(role = CONDITION)
 	CtExpression<Boolean> getCondition();
 
 	/**
 	 * Gets the statement executed when the condition is false.
+	 * <p>
+	 * An {@code else if} like
+	 * <pre>
+	 *     if (a) {
+	 *         doA();
+	 *     } else if (b) {
+	 *         doB();
+	 *     } else {
+	 *         doC();
+	 *     }
+	 * </pre>
+	 * will be represented as
+	 * <pre>
+	 *     if (a) {
+	 *         doA();
+	 *     } else {
+	 *         if (b) {
+	 *             doB();
+	 *         } else {
+	 *             doC();
+	 *         }
+	 *     }
+	 * </pre>
+	 * To differentiate between an {@code else} Block with an {@code if} and an {@code else if},
+	 * {@link CtBlock#isImplicit()} is set to {@code true}.
+	 *
+	 * @return the statement of the {@code else} or {@code null} if no else is specified.
 	 */
 	@PropertyGetter(role = ELSE)
 	<S extends CtStatement> S getElseStatement();
 
 	/**
 	 * Gets the statement executed when the condition is true.
+	 * <p>
+	 * This method will return {@code null} for {@code if (condition);}.
+	 *
+	 * @return the statement of the {@code if}, in most cases this is a {@link CtBlock}.
 	 */
 	@PropertyGetter(role = THEN)
 	<S extends CtStatement> S getThenStatement();
 
 	/**
-	 * Sets the boolean expression that represents the <code>if</code>'s
+	 * Sets the boolean expression that represents the {@code if}'s
 	 * condition.
 	 */
 	@PropertySetter(role = CONDITION)

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

@@ -9,9 +9,9 @@
 
 /**
  * This code element defines a write to a variable.
- *
- * In Java, it is a usage of a variable inside an assignment.
- *
+ * <p>
+ * A variable-write is an assignment to a variable.
+ * <p>
  * For example:
  * <pre>
  *     String variable = "";
@@ -23,8 +23,9 @@
  * </pre>
  *
  *
- * @param <T>
- * 		type of the variable
+ * @param <T> type of the variable
+ * @see CtAssignment#getAssigned()
+ * @see CtArrayWrite
  */
 public interface CtVariableWrite<T> extends CtVariableAccess<T> {
 	@Override

src/main/java/spoon/reflect/declaration/CtTypeInformation.java

@@ -21,12 +21,11 @@
 import static spoon.reflect.path.CtRole.SUPER_TYPE;
 
 /**
- * Returns information that can be obtained both at compile-time and run-time
+ * Returns information that can be obtained both at compile-time and run-time.
  *
- * For CtElement, the compile-time information is given
- *
- * For CtTypeReference, the runtime information is given (using the Reflection API)
+ * For {@link CtElement}, the compile-time information is given.
  *
+ * For {@link CtTypeReference}, the runtime information is given (using the Reflection API)
  */
 public interface CtTypeInformation {
 	/**
@@ -49,21 +48,37 @@ public interface CtTypeInformation {
 	Set<ModifierKind> getModifiers();
 
 	/**
-	 * Return {@code true} if the referenced type is a primitive type (int,
-	 * double, boolean...).
+	 * Checks if the referenced type is a primitive type.
+	 * <p>
+	 * It is a primitive type, if it is one of the following types:
+	 * <ul>
+	 *     <li>byte</li>
+	 *     <li>short</li>
+	 *     <li>int</li>
+	 *     <li>long</li>
+	 *     <li>float</li>
+	 *     <li>double</li>
+	 *     <li>boolean</li>
+	 *     <li>char</li>
+	 *     <li>void</li>
+	 * </ul>
+	 * <p>
+	 * For boxed types like {@link Integer} this method returns {@code false}.
+	 *
+	 * @return {@code true} if the referenced type is a primitive type
 	 */
 	boolean isPrimitive();
 
 	/**
-	 * Return {@code true} if the referenced type is a anonymous type
+	 * Return {@code true} if the referenced type is an anonymous type
 	 */
 	boolean isAnonymous();
 
 	/**
-	 * Return {@code true} if the referenced type is declared in an executable.
+	 * Returns {@code true} if the referenced type is declared in an executable.
 	 * e.g. a type declared in a method or a lambda.
 	 *
-	 * This corresponds to <code>isLocalClass</code> of <code>java.lang.Class</code>.
+	 * This corresponds to {@code isLocalClass} of {@code java.lang.Class}.
 	 *
 	 * <pre>
 	 *     // Type declared in a method.
@@ -115,18 +130,26 @@ public interface CtTypeInformation {
 	boolean isParameterized();
 
 	/**
-	 * Returns true if the referenced type is a sub-type of the given type.
-	 * Returns true is type is self, it means: typeX.isSubtypeOf(typeX) is true too
+	 * Checks if this type is a subtype of the given type.
+	 *
+	 * @param type the type that might be a parent of this type.
+	 * @return {@code true} if the referenced type is a subtype of the given type, otherwise {@code false}.
+	 *         If this type is the same as the given type ({@code typeX.isSubtypeOf(typeX)}),
+	 *         this method returns {@code true}.
 	 */
 	boolean isSubtypeOf(CtTypeReference<?> type);
 
 	/**
-	 * Returns the class type directly extended by this class.
-	 *
-	 * getSuperClass().getDeclaration()/getTypeDeclaration() returns the corresponding CtType (if in the source folder of Spoon).
+	 * Returns a reference to the type directly extended by this type.
+	 * <p>
+	 * To get the {@link CtType} of the super class, use {@link CtTypeReference#getDeclaration()}
+	 * or {@link CtTypeReference#getTypeDeclaration()} on the {@link CtTypeReference} returned by this method.
 	 *
-	 * @return the class type directly extended by this class, or null if there
-	 *         is none or if the super class is not in the classpath (in noclasspath mode)
+	 * @return the type explicitly extended by this type, or {@code null} if there
+	 *         is none or if the super type is not in the classpath (in noclasspath mode).
+	 *         If a class does not explicitly extend another class {@code null} is returned (<b>not</b> {@link Object}).
+	 *         For types like enums that implicitly extend a superclass like {@link Enum}, this method returns
+	 *         that class.
 	 */
 	@PropertyGetter(role = SUPER_TYPE)
 	CtTypeReference<?> getSuperclass();
@@ -147,14 +170,14 @@ public interface CtTypeInformation {
 	/**
 	 * Gets a field from its name.
 	 *
-	 * @return null if does not exit
+	 * @return a reference to the field with the name or {@code null} if it does not exist
 	 */
 	CtFieldReference<?> getDeclaredField(String name);
 
 	/**
 	 * Gets a field from this type or any super type or any implemented interface by field name.
 	 *
-	 * @return null if does not exit
+	 * @return a reference to the field with the name or {@code null} if it does not exist
 	 */
 	CtFieldReference<?> getDeclaredOrInheritedField(String fieldName);
 
@@ -180,15 +203,23 @@ public interface CtTypeInformation {
 	Collection<CtExecutableReference<?>> getAllExecutables();
 
 	/**
-	 * @return the type erasure, which is computed by the java compiler to ensure that no new classes are created for parametrized types so that generics incur no runtime overhead.
-	 * See https://docs.oracle.com/javase/tutorial/java/generics/erasure.html
+	 * This method returns a reference to the erased type.
+	 * <p>
+	 * For example, this will return {@code List} for {@code List<String>},
+	 * or {@code Enum} for the type parameter {@code E} in the enum
+	 * declaration.
+	 *
+	 * @return a reference to the erased type
+	 * @see <a href="https://docs.oracle.com/javase/specs/jls/se20/html/jls-4.html#jls-4.6">Type Erasure</a>
 	 */
 	@DerivedProperty
 	CtTypeReference<?> getTypeErasure();
 
 
 	/**
-	 * @return true if this represents an array e.g. Object[] or int[]
+	 * Returns true if this type represents an array like {@code Object[]} or {@code int[]}.
+	 *
+	 * @return true if this type represents an array like {@code Object[]} or {@code int[]}
 	 */
 	boolean isArray();
 }

src/main/java/spoon/reflect/visitor/chain/CtQueryable.java

@@ -20,6 +20,8 @@
  * </ol>
  *
  * The main methods are documented in CtQuery
+ * <p>
+ * You might want to use {@link Filter} with {@link CtElement#getElements(Filter)} instead.
  */
 public interface CtQueryable {