Skip to content

Commit

Permalink
Improve JavaDoc for core methods
Browse files Browse the repository at this point in the history 
The two mergeFrom methods now specify what actions will be taken on each kind of property (e.g. skip defaults, append collections). The clear method now clarifies that it returns the builder, and the build method uses the term "this builder" rather than "the builder".

The new MergeAction type is responsible for making a readable set of merge actions, emitting sentences like "appending to collections, and skipping defaults and unset properties".
  • Loading branch information
@alicederyn
alicederyn committed Jan 26, 2019
1 parent 75479d4 commit 472daed
Show file tree
Hide file tree
Showing 29 changed files with 664 additions and 245 deletions.
131 changes: 68 additions & 63 deletions src/main/java/org/inferred/freebuilder/processor/BuildableType_Builder.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,14 @@

import com.google.common.annotations.VisibleForTesting;
import com.google.common.base.Preconditions;

import org.inferred.freebuilder.processor.source.Excerpt;
import org.inferred.freebuilder.processor.source.Type;

import java.util.EnumSet;
import java.util.Objects;
import java.util.function.UnaryOperator;

import javax.annotation.Generated;
import org.inferred.freebuilder.processor.BuildableType.MergeBuilderMethod;
import org.inferred.freebuilder.processor.BuildableType.PartialToBuilderMethod;
import org.inferred.freebuilder.processor.source.Excerpt;
import org.inferred.freebuilder.processor.source.Type;

/**
* Auto-generated superclass of {@link BuildableType.Builder}, derived from the API of {@link
Expand Down Expand Up @@ -48,8 +47,8 @@ public String toString() {

private Type type;
private Type builderType;
private BuildableType.MergeBuilderMethod mergeBuilder;
private BuildableType.PartialToBuilderMethod partialToBuilder;
private MergeBuilderMethod mergeBuilder;
private PartialToBuilderMethod partialToBuilder;
private BuilderFactory builderFactory;
private Excerpt suppressUnchecked;
private final EnumSet<Property> _unsetProperties = EnumSet.allOf(Property.class);
Expand Down Expand Up @@ -131,7 +130,7 @@ public Type builderType() {
* @return this {@code Builder} object
* @throws NullPointerException if {@code mergeBuilder} is null
*/
public BuildableType.Builder mergeBuilder(BuildableType.MergeBuilderMethod mergeBuilder) {
public BuildableType.Builder mergeBuilder(MergeBuilderMethod mergeBuilder) {
this.mergeBuilder = Objects.requireNonNull(mergeBuilder);
_unsetProperties.remove(Property.MERGE_BUILDER);
return (BuildableType.Builder) this;
Expand All @@ -145,8 +144,7 @@ public BuildableType.Builder mergeBuilder(BuildableType.MergeBuilderMethod merge
* @throws NullPointerException if {@code mapper} is null or returns null
* @throws IllegalStateException if the field has not been set
*/
public BuildableType.Builder mapMergeBuilder(
UnaryOperator<BuildableType.MergeBuilderMethod> mapper) {
public BuildableType.Builder mapMergeBuilder(UnaryOperator<MergeBuilderMethod> mapper) {
Objects.requireNonNull(mapper);
return mergeBuilder(mapper.apply(mergeBuilder()));
}
Expand All @@ -156,7 +154,7 @@ public BuildableType.Builder mapMergeBuilder(
*
* @throws IllegalStateException if the field has not been set
*/
public BuildableType.MergeBuilderMethod mergeBuilder() {
public MergeBuilderMethod mergeBuilder() {
Preconditions.checkState(
!_unsetProperties.contains(Property.MERGE_BUILDER), "mergeBuilder not set");
return mergeBuilder;
Expand All @@ -168,8 +166,7 @@ public BuildableType.MergeBuilderMethod mergeBuilder() {
* @return this {@code Builder} object
* @throws NullPointerException if {@code partialToBuilder} is null
*/
public BuildableType.Builder partialToBuilder(
BuildableType.PartialToBuilderMethod partialToBuilder) {
public BuildableType.Builder partialToBuilder(PartialToBuilderMethod partialToBuilder) {
this.partialToBuilder = Objects.requireNonNull(partialToBuilder);
_unsetProperties.remove(Property.PARTIAL_TO_BUILDER);
return (BuildableType.Builder) this;
Expand All @@ -183,8 +180,7 @@ public BuildableType.Builder partialToBuilder(
* @throws NullPointerException if {@code mapper} is null or returns null
* @throws IllegalStateException if the field has not been set
*/
public BuildableType.Builder mapPartialToBuilder(
UnaryOperator<BuildableType.PartialToBuilderMethod> mapper) {
public BuildableType.Builder mapPartialToBuilder(UnaryOperator<PartialToBuilderMethod> mapper) {
Objects.requireNonNull(mapper);
return partialToBuilder(mapper.apply(partialToBuilder()));
}
Expand All @@ -194,7 +190,7 @@ public BuildableType.Builder mapPartialToBuilder(
*
* @throws IllegalStateException if the field has not been set
*/
public BuildableType.PartialToBuilderMethod partialToBuilder() {
public PartialToBuilderMethod partialToBuilder() {
Preconditions.checkState(
!_unsetProperties.contains(Property.PARTIAL_TO_BUILDER), "partialToBuilder not set");
return partialToBuilder;
Expand Down Expand Up @@ -272,93 +268,102 @@ public Excerpt suppressUnchecked() {
return suppressUnchecked;
}

/** Sets all property values using the given {@code BuildableType} as a template. */
/**
* Copies values from {@code value}.
*
* @return this {@code Builder} object
*/
public BuildableType.Builder mergeFrom(BuildableType value) {
BuildableType_Builder _defaults = new BuildableType.Builder();
if (_defaults._unsetProperties.contains(Property.TYPE)
|| !Objects.equals(value.type(), _defaults.type())) {
BuildableType_Builder defaults = new BuildableType.Builder();
if (defaults._unsetProperties.contains(Property.TYPE)
|| !Objects.equals(value.type(), defaults.type())) {
type(value.type());
}
if (_defaults._unsetProperties.contains(Property.BUILDER_TYPE)
|| !Objects.equals(value.builderType(), _defaults.builderType())) {
if (defaults._unsetProperties.contains(Property.BUILDER_TYPE)
|| !Objects.equals(value.builderType(), defaults.builderType())) {
builderType(value.builderType());
}
if (_defaults._unsetProperties.contains(Property.MERGE_BUILDER)
|| !Objects.equals(value.mergeBuilder(), _defaults.mergeBuilder())) {
if (defaults._unsetProperties.contains(Property.MERGE_BUILDER)
|| !Objects.equals(value.mergeBuilder(), defaults.mergeBuilder())) {
mergeBuilder(value.mergeBuilder());
}
if (_defaults._unsetProperties.contains(Property.PARTIAL_TO_BUILDER)
|| !Objects.equals(value.partialToBuilder(), _defaults.partialToBuilder())) {
if (defaults._unsetProperties.contains(Property.PARTIAL_TO_BUILDER)
|| !Objects.equals(value.partialToBuilder(), defaults.partialToBuilder())) {
partialToBuilder(value.partialToBuilder());
}
if (_defaults._unsetProperties.contains(Property.BUILDER_FACTORY)
|| !Objects.equals(value.builderFactory(), _defaults.builderFactory())) {
if (defaults._unsetProperties.contains(Property.BUILDER_FACTORY)
|| !Objects.equals(value.builderFactory(), defaults.builderFactory())) {
builderFactory(value.builderFactory());
}
if (_defaults._unsetProperties.contains(Property.SUPPRESS_UNCHECKED)
|| !Objects.equals(value.suppressUnchecked(), _defaults.suppressUnchecked())) {
if (defaults._unsetProperties.contains(Property.SUPPRESS_UNCHECKED)
|| !Objects.equals(value.suppressUnchecked(), defaults.suppressUnchecked())) {
suppressUnchecked(value.suppressUnchecked());
}
return (BuildableType.Builder) this;
}

/**
* Copies values from the given {@code Builder}. Does not affect any properties not set on the
* input.
* Copies values from {@code template}, skipping unset properties.
*
* @return this {@code Builder} object
*/
public BuildableType.Builder mergeFrom(BuildableType.Builder template) {
// Upcast to access private fields; otherwise, oddly, we get an access violation.
BuildableType_Builder base = template;
BuildableType_Builder _defaults = new BuildableType.Builder();
BuildableType_Builder defaults = new BuildableType.Builder();
if (!base._unsetProperties.contains(Property.TYPE)
&& (_defaults._unsetProperties.contains(Property.TYPE)
|| !Objects.equals(template.type(), _defaults.type()))) {
&& (defaults._unsetProperties.contains(Property.TYPE)
|| !Objects.equals(template.type(), defaults.type()))) {
type(template.type());
}
if (!base._unsetProperties.contains(Property.BUILDER_TYPE)
&& (_defaults._unsetProperties.contains(Property.BUILDER_TYPE)
|| !Objects.equals(template.builderType(), _defaults.builderType()))) {
&& (defaults._unsetProperties.contains(Property.BUILDER_TYPE)
|| !Objects.equals(template.builderType(), defaults.builderType()))) {
builderType(template.builderType());
}
if (!base._unsetProperties.contains(Property.MERGE_BUILDER)
&& (_defaults._unsetProperties.contains(Property.MERGE_BUILDER)
|| !Objects.equals(template.mergeBuilder(), _defaults.mergeBuilder()))) {
&& (defaults._unsetProperties.contains(Property.MERGE_BUILDER)
|| !Objects.equals(template.mergeBuilder(), defaults.mergeBuilder()))) {
mergeBuilder(template.mergeBuilder());
}
if (!base._unsetProperties.contains(Property.PARTIAL_TO_BUILDER)
&& (_defaults._unsetProperties.contains(Property.PARTIAL_TO_BUILDER)
|| !Objects.equals(template.partialToBuilder(), _defaults.partialToBuilder()))) {
&& (defaults._unsetProperties.contains(Property.PARTIAL_TO_BUILDER)
|| !Objects.equals(template.partialToBuilder(), defaults.partialToBuilder()))) {
partialToBuilder(template.partialToBuilder());
}
if (!base._unsetProperties.contains(Property.BUILDER_FACTORY)
&& (_defaults._unsetProperties.contains(Property.BUILDER_FACTORY)
|| !Objects.equals(template.builderFactory(), _defaults.builderFactory()))) {
&& (defaults._unsetProperties.contains(Property.BUILDER_FACTORY)
|| !Objects.equals(template.builderFactory(), defaults.builderFactory()))) {
builderFactory(template.builderFactory());
}
if (!base._unsetProperties.contains(Property.SUPPRESS_UNCHECKED)
&& (_defaults._unsetProperties.contains(Property.SUPPRESS_UNCHECKED)
|| !Objects.equals(template.suppressUnchecked(), _defaults.suppressUnchecked()))) {
&& (defaults._unsetProperties.contains(Property.SUPPRESS_UNCHECKED)
|| !Objects.equals(template.suppressUnchecked(), defaults.suppressUnchecked()))) {
suppressUnchecked(template.suppressUnchecked());
}
return (BuildableType.Builder) this;
}

/** Resets the state of this builder. */
/**
* Resets the state of this builder.
*
* @return this {@code Builder} object
*/
public BuildableType.Builder clear() {
BuildableType_Builder _defaults = new BuildableType.Builder();
type = _defaults.type;
builderType = _defaults.builderType;
mergeBuilder = _defaults.mergeBuilder;
partialToBuilder = _defaults.partialToBuilder;
builderFactory = _defaults.builderFactory;
suppressUnchecked = _defaults.suppressUnchecked;
BuildableType_Builder defaults = new BuildableType.Builder();
type = defaults.type;
builderType = defaults.builderType;
mergeBuilder = defaults.mergeBuilder;
partialToBuilder = defaults.partialToBuilder;
builderFactory = defaults.builderFactory;
suppressUnchecked = defaults.suppressUnchecked;
_unsetProperties.clear();
_unsetProperties.addAll(_defaults._unsetProperties);
_unsetProperties.addAll(defaults._unsetProperties);
return (BuildableType.Builder) this;
}

/**
* Returns a newly-created {@link BuildableType} based on the contents of the {@code Builder}.
* Returns a newly-created {@link BuildableType} based on the contents of this {@code Builder}.
*
* @throws IllegalStateException if any field has not been set
*/
Expand All @@ -384,8 +389,8 @@ public BuildableType buildPartial() {
private static final class Value extends BuildableType {
private final Type type;
private final Type builderType;
private final BuildableType.MergeBuilderMethod mergeBuilder;
private final BuildableType.PartialToBuilderMethod partialToBuilder;
private final MergeBuilderMethod mergeBuilder;
private final PartialToBuilderMethod partialToBuilder;
private final BuilderFactory builderFactory;
private final Excerpt suppressUnchecked;

Expand All @@ -409,12 +414,12 @@ public Type builderType() {
}

@Override
public BuildableType.MergeBuilderMethod mergeBuilder() {
public MergeBuilderMethod mergeBuilder() {
return mergeBuilder;
}

@Override
public BuildableType.PartialToBuilderMethod partialToBuilder() {
public PartialToBuilderMethod partialToBuilder() {
return partialToBuilder;
}

Expand Down Expand Up @@ -469,8 +474,8 @@ public String toString() {
private static final class Partial extends BuildableType {
private final Type type;
private final Type builderType;
private final BuildableType.MergeBuilderMethod mergeBuilder;
private final BuildableType.PartialToBuilderMethod partialToBuilder;
private final MergeBuilderMethod mergeBuilder;
private final PartialToBuilderMethod partialToBuilder;
private final BuilderFactory builderFactory;
private final Excerpt suppressUnchecked;
private final EnumSet<Property> _unsetProperties;
Expand Down Expand Up @@ -502,15 +507,15 @@ public Type builderType() {
}

@Override
public BuildableType.MergeBuilderMethod mergeBuilder() {
public MergeBuilderMethod mergeBuilder() {
if (_unsetProperties.contains(Property.MERGE_BUILDER)) {
throw new UnsupportedOperationException("mergeBuilder not set");
}
return mergeBuilder;
}

@Override
public BuildableType.PartialToBuilderMethod partialToBuilder() {
public PartialToBuilderMethod partialToBuilder() {
if (_unsetProperties.contains(Property.PARTIAL_TO_BUILDER)) {
throw new UnsupportedOperationException("partialToBuilder not set");
}
Expand Down
33 changes: 20 additions & 13 deletions src/main/java/org/inferred/freebuilder/processor/Datatype_Builder.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,6 @@
import com.google.common.base.Preconditions;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

import org.inferred.freebuilder.processor.Datatype.StandardMethod;
import org.inferred.freebuilder.processor.Datatype.UnderrideLevel;
import org.inferred.freebuilder.processor.source.Excerpt;
import org.inferred.freebuilder.processor.source.Type;
import org.inferred.freebuilder.processor.source.TypeClass;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
Expand All @@ -26,8 +19,12 @@
import java.util.function.Consumer;
import java.util.function.UnaryOperator;
import java.util.stream.BaseStream;

import javax.annotation.Generated;
import org.inferred.freebuilder.processor.Datatype.StandardMethod;
import org.inferred.freebuilder.processor.Datatype.UnderrideLevel;
import org.inferred.freebuilder.processor.source.Excerpt;
import org.inferred.freebuilder.processor.source.Type;
import org.inferred.freebuilder.processor.source.TypeClass;

/**
* Auto-generated superclass of {@link Datatype.Builder}, derived from the API of {@link Datatype}.
Expand Down Expand Up @@ -968,7 +965,11 @@ public List<Excerpt> getNestedClasses() {
return Collections.unmodifiableList(nestedClasses);
}

/** Sets all property values using the given {@code Datatype} as a template. */
/**
* Copies values from {@code value}, appending to collections, and skipping empty optionals.
*
* @return this {@code Builder} object
*/
public Datatype.Builder mergeFrom(Datatype value) {
Datatype_Builder defaults = new Datatype.Builder();
if (defaults._unsetProperties.contains(Property.TYPE)
Expand Down Expand Up @@ -1036,8 +1037,10 @@ public Datatype.Builder mergeFrom(Datatype value) {
}

/**
* Copies values from the given {@code Builder}. Does not affect any properties not set on the
* input.
* Copies values from {@code template}, appending to collections, and skipping empty optionals and
* unset properties.
*
* @return this {@code Builder} object
*/
public Datatype.Builder mergeFrom(Datatype.Builder template) {
// Upcast to access private fields; otherwise, oddly, we get an access violation.
Expand Down Expand Up @@ -1107,7 +1110,11 @@ public Datatype.Builder mergeFrom(Datatype.Builder template) {
return (Datatype.Builder) this;
}

/** Resets the state of this builder. */
/**
* Resets the state of this builder.
*
* @return this {@code Builder} object
*/
public Datatype.Builder clear() {
Datatype_Builder defaults = new Datatype.Builder();
type = defaults.type;
Expand All @@ -1132,7 +1139,7 @@ public Datatype.Builder clear() {
}

/**
* Returns a newly-created {@link Datatype} based on the contents of the {@code Builder}.
* Returns a newly-created {@link Datatype} based on the contents of this {@code Builder}.
*
* @throws IllegalStateException if any field has not been set
*/
Expand Down
Loading

0 comments on commit 472daed

Please sign in to comment.