From a1039502052cc4f5ed1f22a8801154c698920a76 Mon Sep 17 00:00:00 2001 From: HliasMpGH Date: Mon, 20 May 2024 15:09:23 +0300 Subject: [PATCH 1/3] document Util class methods --- src/main/java/com/squareup/javapoet/Util.java | 66 +++++++++++++++++++ .../squareup/javapoet/WildcardTypeName.java | 1 + 2 files changed, 67 insertions(+) diff --git a/src/main/java/com/squareup/javapoet/Util.java b/src/main/java/com/squareup/javapoet/Util.java index 61b5898..087a2a3 100644 --- a/src/main/java/com/squareup/javapoet/Util.java +++ b/src/main/java/com/squareup/javapoet/Util.java @@ -37,6 +37,12 @@ final class Util { private Util() { } + /** + * Similar to {@link #immutableMap immutableMap}, but used + * for maps that contain lists for values. + * @param multimap a map with list values. + * @return the immutable view of the {@code map}. + */ static Map> immutableMultimap(Map> multimap) { LinkedHashMap> result = new LinkedHashMap<>(); for (Map.Entry> entry : multimap.entrySet()) { @@ -46,31 +52,84 @@ static Map> immutableMultimap(Map> multimap) { return Collections.unmodifiableMap(result); } + /** + * Retrieves an immutable view of a given map. + * @param map a map. + * @return the immutable view of the {@code map}. + */ static Map immutableMap(Map map) { return Collections.unmodifiableMap(new LinkedHashMap<>(map)); } + /** + * Verifies a given condition as satisfied and + * throws an exception otherwise, based on a + * given error message.
+ * Should be preferred for argument checking.
+ * Check {@link #checkState checkState} for state + * checking. + * @param condition the condition to be checked. + * @param format the format that should be used for the exception message. + * @param args the values that should be placed in the holders of the format. + */ static void checkArgument(boolean condition, String format, Object... args) { if (!condition) throw new IllegalArgumentException(String.format(format, args)); } + /** + * Verifies a reference as not null and throws + * an exception otherwise, based on a + * given error message. + * @param reference the reference to be checked. + * @param format the format that should be used for the exception message. + * @param args the values that should be placed in the holders of the format. + * @return the (not null) reference. + */ static T checkNotNull(T reference, String format, Object... args) { if (reference == null) throw new NullPointerException(String.format(format, args)); return reference; } + /** + * Similar to {@link #checkArgument checkArgument}, + * but should be preferred for cases were the state + * of an execution is to be checked. + * @param condition the condition to be checked. + * @param format the format that should be used for the exception message. + * @param args the values that should be placed in the holders of the format. + */ static void checkState(boolean condition, String format, Object... args) { if (!condition) throw new IllegalStateException(String.format(format, args)); } + /** + * Creates an immutable list from a specified collection. + * @param collection a collection of an unspecified type + * that can be transformed to a list. + * @return an immutable list that contains the same elements. + */ static List immutableList(Collection collection) { return Collections.unmodifiableList(new ArrayList<>(collection)); } + /** + * Similar to {@link #immutableList immutableList}, + * but for sets. + * @param set a collection of an unspecified type + * that can be transformed to a set. + * @return an immutable set that contains the same elements. + */ static Set immutableSet(Collection set) { return Collections.unmodifiableSet(new LinkedHashSet<>(set)); } + /** + * Merges two sets and returns the result. + * @param a a set. + * @param b a second set we want to merge into a. + * @return a new set containing the elements of + * both sets. + */ static Set union(Set a, Set b) { Set result = new LinkedHashSet<>(); result.addAll(a); @@ -78,6 +137,13 @@ static Set union(Set a, Set b) { return result; } + /** + * Checks if a set of modifiers contains + * exactly one modifier from + * an array of modifiers. + * @param modifiers the set to be checked for exclusivity. + * @param mutuallyExclusive the modifiers. + */ static void requireExactlyOneOf(Set modifiers, Modifier... mutuallyExclusive) { int count = 0; for (Modifier modifier : mutuallyExclusive) { diff --git a/src/main/java/com/squareup/javapoet/WildcardTypeName.java b/src/main/java/com/squareup/javapoet/WildcardTypeName.java index ff4b16b..7729a3b 100644 --- a/src/main/java/com/squareup/javapoet/WildcardTypeName.java +++ b/src/main/java/com/squareup/javapoet/WildcardTypeName.java @@ -30,6 +30,7 @@ import static com.squareup.javapoet.Util.checkArgument; public final class WildcardTypeName extends TypeName { + /** the type bounds of the WildCardType */ public final List upperBounds; public final List lowerBounds; From 03199d13ac88d305d3899f632b230996d8f2e882 Mon Sep 17 00:00:00 2001 From: HliasMpGH Date: Mon, 27 May 2024 11:31:38 +0300 Subject: [PATCH 2/3] document TypeName and ParameterSpec classes --- .../com/squareup/javapoet/ParameterSpec.java | 13 +++++++++++++ .../java/com/squareup/javapoet/TypeName.java | 17 +++++++++++++++-- 2 files changed, 28 insertions(+), 2 deletions(-) diff --git a/src/main/java/com/squareup/javapoet/ParameterSpec.java b/src/main/java/com/squareup/javapoet/ParameterSpec.java index f4211c2..57cdf47 100644 --- a/src/main/java/com/squareup/javapoet/ParameterSpec.java +++ b/src/main/java/com/squareup/javapoet/ParameterSpec.java @@ -47,6 +47,7 @@ private ParameterSpec(Builder builder) { this.javadoc = builder.javadoc.build(); } + /** Returns true if the ParameterSpec has {@code modifier}. */ public boolean hasModifier(Modifier modifier) { return modifiers.contains(modifier); } @@ -84,6 +85,7 @@ void emit(CodeWriter codeWriter, boolean varargs) throws IOException { } } + /** Builds and returns a ParameterSpec based on a given {@code element}. */ public static ParameterSpec get(VariableElement element) { checkArgument(element.getKind().equals(ElementKind.PARAMETER), "element is not a parameter"); @@ -96,6 +98,7 @@ public static ParameterSpec get(VariableElement element) { .build(); } + /** Collects and returns a List of the parameters of a given {@code method}. */ static List parametersOf(ExecutableElement method) { List result = new ArrayList<>(); for (VariableElement parameter : method.getParameters()) { @@ -104,6 +107,7 @@ static List parametersOf(ExecutableElement method) { return result; } + /** Returns true if {@code name} is a valid parameter name, based on the given version. */ private static boolean isValidParameterName(String name) { // Allow "this" for explicit receiver parameters // See https://docs.oracle.com/javase/specs/jls/se8/html/jls-8.html#jls-8.4.1. @@ -113,6 +117,10 @@ private static boolean isValidParameterName(String name) { return name.equals("this") || SourceVersion.isName(name); } + /** + * Creates and returns a ParameterSpec Builder based + * on a {@code type}, a {@code name} and some {@code modifiers}. + */ public static Builder builder(TypeName type, String name, Modifier... modifiers) { checkNotNull(type, "type == null"); checkArgument(isValidParameterName(name), "not a valid name: %s", name); @@ -124,6 +132,11 @@ public static Builder builder(Type type, String name, Modifier... modifiers) { return builder(TypeName.get(type), name, modifiers); } + /** + * Creates and returns a ParameterSpec Builder + * based on this ParameterSpec's {@code type}, + * {@code name}, {@code annotations} and {@code modifiers}. + */ public Builder toBuilder() { return toBuilder(type, name); } diff --git a/src/main/java/com/squareup/javapoet/TypeName.java b/src/main/java/com/squareup/javapoet/TypeName.java index abffddb..86f4905 100644 --- a/src/main/java/com/squareup/javapoet/TypeName.java +++ b/src/main/java/com/squareup/javapoet/TypeName.java @@ -67,6 +67,7 @@ * ParameterizedTypeName}, {@link TypeVariableName}, and {@link WildcardTypeName}. */ public class TypeName { + /** All available primitive types of Java (+ void) */ public static final TypeName VOID = new TypeName("void"); public static final TypeName BOOLEAN = new TypeName("boolean"); public static final TypeName BYTE = new TypeName("byte"); @@ -76,8 +77,9 @@ public class TypeName { public static final TypeName CHAR = new TypeName("char"); public static final TypeName FLOAT = new TypeName("float"); public static final TypeName DOUBLE = new TypeName("double"); - public static final ClassName OBJECT = ClassName.get("java.lang", "Object"); + /** All available wrapper/ boxed types of Java (+ Object and void) */ + public static final ClassName OBJECT = ClassName.get("java.lang", "Object"); private static final ClassName BOXED_VOID = ClassName.get("java.lang", "Void"); private static final ClassName BOXED_BOOLEAN = ClassName.get("java.lang", "Boolean"); private static final ClassName BOXED_BYTE = ClassName.get("java.lang", "Byte"); @@ -99,12 +101,13 @@ private TypeName(String keyword) { this(keyword, new ArrayList<>()); } + /** Creates a new TypeName instance named {@code keyword} with its {@code annotations} */ private TypeName(String keyword, List annotations) { this.keyword = keyword; this.annotations = Util.immutableList(annotations); } - // Package-private constructor to prevent third-party subclasses. + /** Package-private constructor to prevent third-party subclasses. */ TypeName(List annotations) { this(null, annotations); } @@ -118,6 +121,11 @@ public TypeName annotated(List annotations) { return new TypeName(keyword, concatAnnotations(annotations)); } + /** + * Returns a TypeName with no annotations. + * If this TypeName is not annotated, + * it returns this TypeName. + */ public TypeName withoutAnnotations() { if (annotations.isEmpty()) { return this; @@ -125,12 +133,17 @@ public TypeName withoutAnnotations() { return new TypeName(keyword); } + /** + * Given a list of {@code annotations}, returns a new one + * that is a union of the input list and this TypeName's annotations. + */ protected final List concatAnnotations(List annotations) { List allAnnotations = new ArrayList<>(this.annotations); allAnnotations.addAll(annotations); return allAnnotations; } + /** Returns true if this TypeName has any annotations */ public boolean isAnnotated() { return !annotations.isEmpty(); } From b3030734d1e817c086400bfda29e4a459729976d Mon Sep 17 00:00:00 2001 From: AlexisMardas Date: Sat, 8 Jun 2024 07:20:15 +0300 Subject: [PATCH 3/3] Improve documentation of FieldSpec and MethodSpec --- .../java/com/squareup/javapoet/FieldSpec.java | 83 +++++- .../com/squareup/javapoet/MethodSpec.java | 259 ++++++++++++++++-- 2 files changed, 315 insertions(+), 27 deletions(-) diff --git a/src/main/java/com/squareup/javapoet/FieldSpec.java b/src/main/java/com/squareup/javapoet/FieldSpec.java index 539ddd1..aaf365d 100644 --- a/src/main/java/com/squareup/javapoet/FieldSpec.java +++ b/src/main/java/com/squareup/javapoet/FieldSpec.java @@ -49,10 +49,21 @@ private FieldSpec(Builder builder) { : builder.initializer; } + /** + * Checks if this field has the modifier that is specified. + * @param modifier the modifier to check for + * @return true if the field has the modifier, false otherwise + */ public boolean hasModifier(Modifier modifier) { return modifiers.contains(modifier); } + /** + * Uses the given CodeWriter to emit this field . + * @param codeWriter the code writer used to emit the field + * @param implicitModifiers the set of the field's implicit modifiers + * @throws IOException if an I/O error occurs + */ void emit(CodeWriter codeWriter, Set implicitModifiers) throws IOException { codeWriter.emitJavadoc(javadoc); codeWriter.emitAnnotations(annotations, false); @@ -87,6 +98,13 @@ void emit(CodeWriter codeWriter, Set implicitModifiers) throws IOExcep } } + /** + * Returns a new builder for a {@link FieldSpec}. + * @param type the type of the field + * @param name the name of the field + * @param modifiers the modifiers to apply to the field + * @return a new FieldSpec builder + */ public static Builder builder(TypeName type, String name, Modifier... modifiers) { checkNotNull(type, "type == null"); checkArgument(SourceVersion.isName(name), "not a valid name: %s", name); @@ -94,10 +112,22 @@ public static Builder builder(TypeName type, String name, Modifier... modifiers) .addModifiers(modifiers); } + /** + * Returns a new builder for a FieldSpec. + * @param type the type of the field + * @param name the name of the field + * @param modifiers the modifiers to apply to the field + * @return a new FieldSpec builder + */ public static Builder builder(Type type, String name, Modifier... modifiers) { return builder(TypeName.get(type), name, modifiers); } + /** + * Creates and returns a new builder using the values of an already + * existing FieldSpec + * @return the new builder + */ public Builder toBuilder() { Builder builder = new Builder(type, name); builder.javadoc.add(javadoc); @@ -122,16 +152,32 @@ private Builder(TypeName type, String name) { this.name = name; } + /** + * Adds the Javadoc comment to the builder of the field. + * @param format the format of the Javadoc comment + * @param args the arguments to replace the format's placehoders + * @return this builder + */ public Builder addJavadoc(String format, Object... args) { javadoc.add(format, args); return this; } + /** + * Adds the Javadoc comment to the builder of the field. + * @param block the body of the Javadoc comment + * @return this builder + */ public Builder addJavadoc(CodeBlock block) { javadoc.add(block); return this; } + /** + * Adds the annotations to the builder of the FieldSpec. + * @param annotationSpecs the annotations to be added + * @return this builder + */ public Builder addAnnotations(Iterable annotationSpecs) { checkArgument(annotationSpecs != null, "annotationSpecs == null"); for (AnnotationSpec annotationSpec : annotationSpecs) { @@ -140,35 +186,70 @@ public Builder addAnnotations(Iterable annotationSpecs) { return this; } + /** + * Used to add a single annotation to the builder of the FieldSpec. + * @param annotationSpec the annotation to be added + * @return this builder + */ public Builder addAnnotation(AnnotationSpec annotationSpec) { this.annotations.add(annotationSpec); return this; } + /** + * Used to add a single annotation to the builder of the FieldSpec. + * @param annotation the ClassName representing the annotation's class + * @return this builder + */ public Builder addAnnotation(ClassName annotation) { this.annotations.add(AnnotationSpec.builder(annotation).build()); return this; } + /** + * Used to add a single annotation to the builder of the FieldSpec. + * @param annotation the Class of the annotation + * @return this builder + */ public Builder addAnnotation(Class annotation) { return addAnnotation(ClassName.get(annotation)); } + /** + * Adds modifiers to the builder of the FieldSpec + * @param modifiers the modifiers to be added + * @return this builder + */ public Builder addModifiers(Modifier... modifiers) { Collections.addAll(this.modifiers, modifiers); return this; } + /** + * Adds the initializer of the field + * @param format the format of the initializer + * @param args the arguments to replace the format's placeholders + * @return this builder + */ public Builder initializer(String format, Object... args) { return initializer(CodeBlock.of(format, args)); } + /** + * Adds the initializer of the field + * @param codeBlock the code block of the initializer + * @return this builder + */ public Builder initializer(CodeBlock codeBlock) { checkState(this.initializer == null, "initializer was already set"); this.initializer = checkNotNull(codeBlock, "codeBlock == null"); return this; } - + + /** + * Builds the FieldSpec instance + * @return the built FieldSpec + */ public FieldSpec build() { return new FieldSpec(this); } diff --git a/src/main/java/com/squareup/javapoet/MethodSpec.java b/src/main/java/com/squareup/javapoet/MethodSpec.java index 6914858..3f761cd 100644 --- a/src/main/java/com/squareup/javapoet/MethodSpec.java +++ b/src/main/java/com/squareup/javapoet/MethodSpec.java @@ -76,11 +76,24 @@ private MethodSpec(Builder builder) { this.code = code; } + /** + * Checks whether or not the last parameter is an array + * @param parameters the parameters of the {@link MethodSpec} + * @return true if the last parameter is an array, false otherwise + */ private boolean lastParameterIsArray(List parameters) { return !parameters.isEmpty() && TypeName.asArray((parameters.get(parameters.size() - 1).type)) != null; } + /** + * Emits the method using the given code writer. + * @param codeWriter the code writer used to emit the method + * @param enclosingName the class or interface that contains the method being generated. + * Typically used when generating constructors, or methods that belong to inner classes. + * @param implicitModifiers the set of the method's implicit modifiers + * @throws IOException if an I/O error occurs + */ void emit(CodeWriter codeWriter, String enclosingName, Set implicitModifiers) throws IOException { codeWriter.emitJavadoc(javadocWithParameters()); @@ -141,6 +154,11 @@ void emit(CodeWriter codeWriter, String enclosingName, Set implicitMod codeWriter.popTypeVariables(typeVariables); } + /** + * Builds and returns a Javadoc comment that contains the annotation + * and the comment for each parameter of the {@link MethodSpec}. + * @return the CodeBlock representing the Javadoc comment + */ private CodeBlock javadocWithParameters() { CodeBlock.Builder builder = javadoc.toBuilder(); boolean emitTagNewline = true; @@ -155,10 +173,19 @@ private CodeBlock javadocWithParameters() { return builder.build(); } + /** + * Checks if the method has the specified modifier. + * @param modifier the modifier to search for + * @return true if the modifier is found, false otherwise + */ public boolean hasModifier(Modifier modifier) { return modifiers.contains(modifier); } + /** + * Checks if the method is a constructor + * @return true if the method is a constructor, false otherwise + */ public boolean isConstructor() { return name.equals(CONSTRUCTOR); } @@ -185,10 +212,19 @@ public boolean isConstructor() { } } + /** + * Creates and returns the builder of a {@link MethodSpec} + * @param name the name of the method + * @return the builder of the MethodSpec + */ public static Builder methodBuilder(String name) { return new Builder(name); } + /** + * Creates and returns the builder of a constructor + * @return the builder of the constructor + */ public static Builder constructorBuilder() { return new Builder(CONSTRUCTOR); } @@ -277,6 +313,10 @@ public static Builder overriding( return builder; } + /** + * Creates a new builder, using the values of the existing {@link MethodSpec}. + * @return the builder of the MethodSpec + */ public Builder toBuilder() { Builder builder = new Builder(name); builder.javadoc.add(javadoc); @@ -310,7 +350,13 @@ public static final class Builder { private Builder(String name) { setName(name); } - + + /** + * Validates and sets the name of the method. It also initializes the + * method's return type to void, or null if the method is a constructor. + * @param name the name of the method + * @return this builder + */ public Builder setName(String name) { checkNotNull(name, "name == null"); checkArgument(name.equals(CONSTRUCTOR) || SourceVersion.isName(name), @@ -319,17 +365,33 @@ public Builder setName(String name) { this.returnType = name.equals(CONSTRUCTOR) ? null : TypeName.VOID; return this; } - + + /** + * Adds a Javadoc comment to the method. + * @param format the string format of the Javadoc comment + * @param args the values to replace the format's placeholders + * @return this builder + */ public Builder addJavadoc(String format, Object... args) { javadoc.add(format, args); return this; } - + + /** + * Adds a Javadoc comment to the method. + * @param block the code block that represents the Javadoc comment + * @return this builder + */ public Builder addJavadoc(CodeBlock block) { javadoc.add(block); return this; } - + + /** + * Adds the annotations to the method. + * @param annotationSpecs the annotations to be added + * @return this builder + */ public Builder addAnnotations(Iterable annotationSpecs) { checkArgument(annotationSpecs != null, "annotationSpecs == null"); for (AnnotationSpec annotationSpec : annotationSpecs) { @@ -337,27 +399,51 @@ public Builder addAnnotations(Iterable annotationSpecs) { } return this; } - + + /** + * Adds an annotation to the method. + * @param annotationSpec the annotation to be added + * @return this builder + */ public Builder addAnnotation(AnnotationSpec annotationSpec) { this.annotations.add(annotationSpec); return this; } + /** + * Used to add a single annotation to the method. + * @param annotation the ClassName representing the annotation's class + * @return this builder + */ public Builder addAnnotation(ClassName annotation) { this.annotations.add(AnnotationSpec.builder(annotation).build()); return this; } - + + /** + * Used to add a single annotation to the method. + * @param annotation the Class of the annotation + * @return this builder + */ public Builder addAnnotation(Class annotation) { return addAnnotation(ClassName.get(annotation)); } - + /** + * Adds the modifiers to the method. + * @param modifiers the modifiers to be added + * @return this builder + */ public Builder addModifiers(Modifier... modifiers) { checkNotNull(modifiers, "modifiers == null"); Collections.addAll(this.modifiers, modifiers); return this; } - + + /** + * Adds the modifiers to the method. + * @param modifiers the modifiers to be added + * @return this builder + */ public Builder addModifiers(Iterable modifiers) { checkNotNull(modifiers, "modifiers == null"); for (Modifier modifier : modifiers) { @@ -365,7 +451,11 @@ public Builder addModifiers(Iterable modifiers) { } return this; } - + /** + * Adds type variables, such as , to the method declaration. + * @param typeVariables the type variables to be added + * @return this builder + */ public Builder addTypeVariables(Iterable typeVariables) { checkArgument(typeVariables != null, "typeVariables == null"); for (TypeVariableName typeVariable : typeVariables) { @@ -373,22 +463,42 @@ public Builder addTypeVariables(Iterable typeVariables) { } return this; } - + + /** + * Adds a type variable, such as , to the method declaration. + * @param typeVariable the type variable to be added + * @return this builder + */ public Builder addTypeVariable(TypeVariableName typeVariable) { typeVariables.add(typeVariable); return this; } - + + /** + * Adds the method's return type. + * @param returnType the method's return type + * @return this builder + */ public Builder returns(TypeName returnType) { checkState(!name.equals(CONSTRUCTOR), "constructor cannot have return type."); this.returnType = returnType; return this; } - + + /** + * Adds the method's return type. + * @param returnType the method's return type + * @return this builder + */ public Builder returns(Type returnType) { return returns(TypeName.get(returnType)); } - + + /** + * Adds parameters to the method. + * @param parameterSpecs the parameters to be added + * @return this builder + */ public Builder addParameters(Iterable parameterSpecs) { checkArgument(parameterSpecs != null, "parameterSpecs == null"); for (ParameterSpec parameterSpec : parameterSpecs) { @@ -396,29 +506,62 @@ public Builder addParameters(Iterable parameterSpecs) { } return this; } - + + /** + * Adds a single parameter to the method. + * @param parameterSpec the parameter to be added + * @return this builder + */ public Builder addParameter(ParameterSpec parameterSpec) { this.parameters.add(parameterSpec); return this; } - + + /** + * Adds a single parameter to the method. + * @param type the type of the parameter + * @param name the name of the parameter + * @param modifiers the parameter's modifiers + * @return this builder + */ public Builder addParameter(TypeName type, String name, Modifier... modifiers) { return addParameter(ParameterSpec.builder(type, name, modifiers).build()); } - + + /** + * Adds a single parameter to the method. + * @param type the type of the parameter + * @param name the name of the parameter + * @param modifiers the parameter's modifiers + * @return this builder + */ public Builder addParameter(Type type, String name, Modifier... modifiers) { return addParameter(TypeName.get(type), name, modifiers); } + /** + * States whether or not the method has a varargs parameter, such as args... + * @return this builder + */ public Builder varargs() { return varargs(true); } - + + /** + * States whether or not the method has a varargs parameter, such as args... + * @param varargs true if the method has a varargs parameter, false otherwise + * @return this builder + */ public Builder varargs(boolean varargs) { this.varargs = varargs; return this; } - + + /** + * Adds the Exceptions in the method declaration. + * @param exceptions the names of the classes of the Exceptions + * @return this builder + */ public Builder addExceptions(Iterable exceptions) { checkArgument(exceptions != null, "exceptions == null"); for (TypeName exception : exceptions) { @@ -427,39 +570,84 @@ public Builder addExceptions(Iterable exceptions) { return this; } + /** + * Adds an Exception to the method declaration. + * @param exception the name of the class of the Exception + * @return this builder + */ public Builder addException(TypeName exception) { this.exceptions.add(exception); return this; } - + + /** + * Adds an Exception to the method declaration. + * @param exception the type of the Exception + * @return this builder + */ public Builder addException(Type exception) { return addException(TypeName.get(exception)); } - + + /** + * Adds the body of the method. + * @param format the string format of the method's body + * @param args the values to replace the format's placeholders + * @return this builder + */ public Builder addCode(String format, Object... args) { code.add(format, args); return this; } - + + /** + * Adds the body of the method. + * @param format the string format of the method's body + * @param args the values to replace the named arguments used as + * placeholders in the format + * @return this builder + */ public Builder addNamedCode(String format, Map args) { code.addNamed(format, args); return this; } + /** + * Adds the body of the method. + * @param codeBlock the code block representing the body of the method + * @return this builder + */ public Builder addCode(CodeBlock codeBlock) { code.add(codeBlock); return this; } + /** + * Adds a single-line comment to the method. + * @param format the string format of the comment + * @param args the values to replace the format's placeholders + * @return this builder + */ public Builder addComment(String format, Object... args) { code.add("// " + format + "\n", args); return this; } - + + /** + * Used to specify the default value of an annotation member. + * @param format the string format of the default value + * @param args the value to replace the format's placeholders + * @return this builder + */ public Builder defaultValue(String format, Object... args) { return defaultValue(CodeBlock.of(format, args)); } - + + /** + * Used to specify the default value of an annotation member. + * @param codeBlock the code block representing the default value + * @return this builder + */ public Builder defaultValue(CodeBlock codeBlock) { checkState(this.defaultValue == null, "defaultValue was already set"); this.defaultValue = checkNotNull(codeBlock, "codeBlock == null"); @@ -500,6 +688,10 @@ public Builder nextControlFlow(CodeBlock codeBlock) { return nextControlFlow("$L", codeBlock); } + /** + * Ends the control flow + * @return this builder + */ public Builder endControlFlow() { code.endControlFlow(); return this; @@ -521,17 +713,32 @@ public Builder endControlFlow(String controlFlow, Object... args) { public Builder endControlFlow(CodeBlock codeBlock) { return endControlFlow("$L", codeBlock); } - + + /** + * Adds a statement to the body of the method. + * @param format the string format of the statement + * @param args the values to replace the placeholders of the format + * @return this builder + */ public Builder addStatement(String format, Object... args) { code.addStatement(format, args); return this; } - + + /** + * Adds a statement to the body of the method. + * @param codeBlock the code block that represents the statement + * @return this builder + */ public Builder addStatement(CodeBlock codeBlock) { code.addStatement(codeBlock); return this; } - + + /** + * Builds and returns an instance of {@link MethodSpec} + * @return the built MethodSpec + */ public MethodSpec build() { return new MethodSpec(this); }