Skip to content
This repository was archived by the owner on Oct 16, 2024. It is now read-only.

Commit 0bd85a9

Browse files
alicederynalicederyn
committed
Improve JavaDoc for core methods
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".
1 parent 75479d4 commit 0bd85a9

29 files changed

+655
-226
lines changed

‎src/main/java/org/inferred/freebuilder/processor/BuildableType_Builder.java

+66-58
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44
import com.google.common.annotations.VisibleForTesting;
55
import com.google.common.base.Preconditions;
66

7+
import org.inferred.freebuilder.processor.BuildableType.MergeBuilderMethod;
8+
import org.inferred.freebuilder.processor.BuildableType.PartialToBuilderMethod;
79
import org.inferred.freebuilder.processor.source.Excerpt;
810
import org.inferred.freebuilder.processor.source.Type;
911

@@ -48,8 +50,8 @@ public String toString() {
4850

4951
private Type type;
5052
private Type builderType;
51-
private BuildableType.MergeBuilderMethod mergeBuilder;
52-
private BuildableType.PartialToBuilderMethod partialToBuilder;
53+
private MergeBuilderMethod mergeBuilder;
54+
private PartialToBuilderMethod partialToBuilder;
5355
private BuilderFactory builderFactory;
5456
private Excerpt suppressUnchecked;
5557
private final EnumSet<Property> _unsetProperties = EnumSet.allOf(Property.class);
@@ -131,7 +133,7 @@ public Type builderType() {
131133
* @return this {@code Builder} object
132134
* @throws NullPointerException if {@code mergeBuilder} is null
133135
*/
134-
public BuildableType.Builder mergeBuilder(BuildableType.MergeBuilderMethod mergeBuilder) {
136+
public BuildableType.Builder mergeBuilder(MergeBuilderMethod mergeBuilder) {
135137
this.mergeBuilder = Objects.requireNonNull(mergeBuilder);
136138
_unsetProperties.remove(Property.MERGE_BUILDER);
137139
return (BuildableType.Builder) this;
@@ -145,8 +147,7 @@ public BuildableType.Builder mergeBuilder(BuildableType.MergeBuilderMethod merge
145147
* @throws NullPointerException if {@code mapper} is null or returns null
146148
* @throws IllegalStateException if the field has not been set
147149
*/
148-
public BuildableType.Builder mapMergeBuilder(
149-
UnaryOperator<BuildableType.MergeBuilderMethod> mapper) {
150+
public BuildableType.Builder mapMergeBuilder(UnaryOperator<MergeBuilderMethod> mapper) {
150151
Objects.requireNonNull(mapper);
151152
return mergeBuilder(mapper.apply(mergeBuilder()));
152153
}
@@ -156,7 +157,7 @@ public BuildableType.Builder mapMergeBuilder(
156157
*
157158
* @throws IllegalStateException if the field has not been set
158159
*/
159-
public BuildableType.MergeBuilderMethod mergeBuilder() {
160+
public MergeBuilderMethod mergeBuilder() {
160161
Preconditions.checkState(
161162
!_unsetProperties.contains(Property.MERGE_BUILDER), "mergeBuilder not set");
162163
return mergeBuilder;
@@ -168,8 +169,7 @@ public BuildableType.MergeBuilderMethod mergeBuilder() {
168169
* @return this {@code Builder} object
169170
* @throws NullPointerException if {@code partialToBuilder} is null
170171
*/
171-
public BuildableType.Builder partialToBuilder(
172-
BuildableType.PartialToBuilderMethod partialToBuilder) {
172+
public BuildableType.Builder partialToBuilder(PartialToBuilderMethod partialToBuilder) {
173173
this.partialToBuilder = Objects.requireNonNull(partialToBuilder);
174174
_unsetProperties.remove(Property.PARTIAL_TO_BUILDER);
175175
return (BuildableType.Builder) this;
@@ -183,8 +183,7 @@ public BuildableType.Builder partialToBuilder(
183183
* @throws NullPointerException if {@code mapper} is null or returns null
184184
* @throws IllegalStateException if the field has not been set
185185
*/
186-
public BuildableType.Builder mapPartialToBuilder(
187-
UnaryOperator<BuildableType.PartialToBuilderMethod> mapper) {
186+
public BuildableType.Builder mapPartialToBuilder(UnaryOperator<PartialToBuilderMethod> mapper) {
188187
Objects.requireNonNull(mapper);
189188
return partialToBuilder(mapper.apply(partialToBuilder()));
190189
}
@@ -194,7 +193,7 @@ public BuildableType.Builder mapPartialToBuilder(
194193
*
195194
* @throws IllegalStateException if the field has not been set
196195
*/
197-
public BuildableType.PartialToBuilderMethod partialToBuilder() {
196+
public PartialToBuilderMethod partialToBuilder() {
198197
Preconditions.checkState(
199198
!_unsetProperties.contains(Property.PARTIAL_TO_BUILDER), "partialToBuilder not set");
200199
return partialToBuilder;
@@ -272,93 +271,102 @@ public Excerpt suppressUnchecked() {
272271
return suppressUnchecked;
273272
}
274273

275-
/** Sets all property values using the given {@code BuildableType} as a template. */
274+
/**
275+
* Copies values from {@code value}.
276+
*
277+
* @return this {@code Builder} object
278+
*/
276279
public BuildableType.Builder mergeFrom(BuildableType value) {
277-
BuildableType_Builder _defaults = new BuildableType.Builder();
278-
if (_defaults._unsetProperties.contains(Property.TYPE)
279-
|| !Objects.equals(value.type(), _defaults.type())) {
280+
BuildableType_Builder defaults = new BuildableType.Builder();
281+
if (defaults._unsetProperties.contains(Property.TYPE)
282+
|| !Objects.equals(value.type(), defaults.type())) {
280283
type(value.type());
281284
}
282-
if (_defaults._unsetProperties.contains(Property.BUILDER_TYPE)
283-
|| !Objects.equals(value.builderType(), _defaults.builderType())) {
285+
if (defaults._unsetProperties.contains(Property.BUILDER_TYPE)
286+
|| !Objects.equals(value.builderType(), defaults.builderType())) {
284287
builderType(value.builderType());
285288
}
286-
if (_defaults._unsetProperties.contains(Property.MERGE_BUILDER)
287-
|| !Objects.equals(value.mergeBuilder(), _defaults.mergeBuilder())) {
289+
if (defaults._unsetProperties.contains(Property.MERGE_BUILDER)
290+
|| !Objects.equals(value.mergeBuilder(), defaults.mergeBuilder())) {
288291
mergeBuilder(value.mergeBuilder());
289292
}
290-
if (_defaults._unsetProperties.contains(Property.PARTIAL_TO_BUILDER)
291-
|| !Objects.equals(value.partialToBuilder(), _defaults.partialToBuilder())) {
293+
if (defaults._unsetProperties.contains(Property.PARTIAL_TO_BUILDER)
294+
|| !Objects.equals(value.partialToBuilder(), defaults.partialToBuilder())) {
292295
partialToBuilder(value.partialToBuilder());
293296
}
294-
if (_defaults._unsetProperties.contains(Property.BUILDER_FACTORY)
295-
|| !Objects.equals(value.builderFactory(), _defaults.builderFactory())) {
297+
if (defaults._unsetProperties.contains(Property.BUILDER_FACTORY)
298+
|| !Objects.equals(value.builderFactory(), defaults.builderFactory())) {
296299
builderFactory(value.builderFactory());
297300
}
298-
if (_defaults._unsetProperties.contains(Property.SUPPRESS_UNCHECKED)
299-
|| !Objects.equals(value.suppressUnchecked(), _defaults.suppressUnchecked())) {
301+
if (defaults._unsetProperties.contains(Property.SUPPRESS_UNCHECKED)
302+
|| !Objects.equals(value.suppressUnchecked(), defaults.suppressUnchecked())) {
300303
suppressUnchecked(value.suppressUnchecked());
301304
}
302305
return (BuildableType.Builder) this;
303306
}
304307

305308
/**
306-
* Copies values from the given {@code Builder}. Does not affect any properties not set on the
307-
* input.
309+
* Copies values from {@code template}, skipping unset properties.
310+
*
311+
* @return this {@code Builder} object
308312
*/
309313
public BuildableType.Builder mergeFrom(BuildableType.Builder template) {
310314
// Upcast to access private fields; otherwise, oddly, we get an access violation.
311315
BuildableType_Builder base = template;
312-
BuildableType_Builder _defaults = new BuildableType.Builder();
316+
BuildableType_Builder defaults = new BuildableType.Builder();
313317
if (!base._unsetProperties.contains(Property.TYPE)
314-
&& (_defaults._unsetProperties.contains(Property.TYPE)
315-
|| !Objects.equals(template.type(), _defaults.type()))) {
318+
&& (defaults._unsetProperties.contains(Property.TYPE)
319+
|| !Objects.equals(template.type(), defaults.type()))) {
316320
type(template.type());
317321
}
318322
if (!base._unsetProperties.contains(Property.BUILDER_TYPE)
319-
&& (_defaults._unsetProperties.contains(Property.BUILDER_TYPE)
320-
|| !Objects.equals(template.builderType(), _defaults.builderType()))) {
323+
&& (defaults._unsetProperties.contains(Property.BUILDER_TYPE)
324+
|| !Objects.equals(template.builderType(), defaults.builderType()))) {
321325
builderType(template.builderType());
322326
}
323327
if (!base._unsetProperties.contains(Property.MERGE_BUILDER)
324-
&& (_defaults._unsetProperties.contains(Property.MERGE_BUILDER)
325-
|| !Objects.equals(template.mergeBuilder(), _defaults.mergeBuilder()))) {
328+
&& (defaults._unsetProperties.contains(Property.MERGE_BUILDER)
329+
|| !Objects.equals(template.mergeBuilder(), defaults.mergeBuilder()))) {
326330
mergeBuilder(template.mergeBuilder());
327331
}
328332
if (!base._unsetProperties.contains(Property.PARTIAL_TO_BUILDER)
329-
&& (_defaults._unsetProperties.contains(Property.PARTIAL_TO_BUILDER)
330-
|| !Objects.equals(template.partialToBuilder(), _defaults.partialToBuilder()))) {
333+
&& (defaults._unsetProperties.contains(Property.PARTIAL_TO_BUILDER)
334+
|| !Objects.equals(template.partialToBuilder(), defaults.partialToBuilder()))) {
331335
partialToBuilder(template.partialToBuilder());
332336
}
333337
if (!base._unsetProperties.contains(Property.BUILDER_FACTORY)
334-
&& (_defaults._unsetProperties.contains(Property.BUILDER_FACTORY)
335-
|| !Objects.equals(template.builderFactory(), _defaults.builderFactory()))) {
338+
&& (defaults._unsetProperties.contains(Property.BUILDER_FACTORY)
339+
|| !Objects.equals(template.builderFactory(), defaults.builderFactory()))) {
336340
builderFactory(template.builderFactory());
337341
}
338342
if (!base._unsetProperties.contains(Property.SUPPRESS_UNCHECKED)
339-
&& (_defaults._unsetProperties.contains(Property.SUPPRESS_UNCHECKED)
340-
|| !Objects.equals(template.suppressUnchecked(), _defaults.suppressUnchecked()))) {
343+
&& (defaults._unsetProperties.contains(Property.SUPPRESS_UNCHECKED)
344+
|| !Objects.equals(template.suppressUnchecked(), defaults.suppressUnchecked()))) {
341345
suppressUnchecked(template.suppressUnchecked());
342346
}
343347
return (BuildableType.Builder) this;
344348
}
345349

346-
/** Resets the state of this builder. */
350+
/**
351+
* Resets the state of this builder.
352+
*
353+
* @return this {@code Builder} object
354+
*/
347355
public BuildableType.Builder clear() {
348-
BuildableType_Builder _defaults = new BuildableType.Builder();
349-
type = _defaults.type;
350-
builderType = _defaults.builderType;
351-
mergeBuilder = _defaults.mergeBuilder;
352-
partialToBuilder = _defaults.partialToBuilder;
353-
builderFactory = _defaults.builderFactory;
354-
suppressUnchecked = _defaults.suppressUnchecked;
356+
BuildableType_Builder defaults = new BuildableType.Builder();
357+
type = defaults.type;
358+
builderType = defaults.builderType;
359+
mergeBuilder = defaults.mergeBuilder;
360+
partialToBuilder = defaults.partialToBuilder;
361+
builderFactory = defaults.builderFactory;
362+
suppressUnchecked = defaults.suppressUnchecked;
355363
_unsetProperties.clear();
356-
_unsetProperties.addAll(_defaults._unsetProperties);
364+
_unsetProperties.addAll(defaults._unsetProperties);
357365
return (BuildableType.Builder) this;
358366
}
359367

360368
/**
361-
* Returns a newly-created {@link BuildableType} based on the contents of the {@code Builder}.
369+
* Returns a newly-created {@link BuildableType} based on the contents of this {@code Builder}.
362370
*
363371
* @throws IllegalStateException if any field has not been set
364372
*/
@@ -384,8 +392,8 @@ public BuildableType buildPartial() {
384392
private static final class Value extends BuildableType {
385393
private final Type type;
386394
private final Type builderType;
387-
private final BuildableType.MergeBuilderMethod mergeBuilder;
388-
private final BuildableType.PartialToBuilderMethod partialToBuilder;
395+
private final MergeBuilderMethod mergeBuilder;
396+
private final PartialToBuilderMethod partialToBuilder;
389397
private final BuilderFactory builderFactory;
390398
private final Excerpt suppressUnchecked;
391399

@@ -409,12 +417,12 @@ public Type builderType() {
409417
}
410418

411419
@Override
412-
public BuildableType.MergeBuilderMethod mergeBuilder() {
420+
public MergeBuilderMethod mergeBuilder() {
413421
return mergeBuilder;
414422
}
415423

416424
@Override
417-
public BuildableType.PartialToBuilderMethod partialToBuilder() {
425+
public PartialToBuilderMethod partialToBuilder() {
418426
return partialToBuilder;
419427
}
420428

@@ -469,8 +477,8 @@ public String toString() {
469477
private static final class Partial extends BuildableType {
470478
private final Type type;
471479
private final Type builderType;
472-
private final BuildableType.MergeBuilderMethod mergeBuilder;
473-
private final BuildableType.PartialToBuilderMethod partialToBuilder;
480+
private final MergeBuilderMethod mergeBuilder;
481+
private final PartialToBuilderMethod partialToBuilder;
474482
private final BuilderFactory builderFactory;
475483
private final Excerpt suppressUnchecked;
476484
private final EnumSet<Property> _unsetProperties;
@@ -502,15 +510,15 @@ public Type builderType() {
502510
}
503511

504512
@Override
505-
public BuildableType.MergeBuilderMethod mergeBuilder() {
513+
public MergeBuilderMethod mergeBuilder() {
506514
if (_unsetProperties.contains(Property.MERGE_BUILDER)) {
507515
throw new UnsupportedOperationException("mergeBuilder not set");
508516
}
509517
return mergeBuilder;
510518
}
511519

512520
@Override
513-
public BuildableType.PartialToBuilderMethod partialToBuilder() {
521+
public PartialToBuilderMethod partialToBuilder() {
514522
if (_unsetProperties.contains(Property.PARTIAL_TO_BUILDER)) {
515523
throw new UnsupportedOperationException("partialToBuilder not set");
516524
}

‎src/main/java/org/inferred/freebuilder/processor/Datatype_Builder.java

+15-5
Original file line numberDiff line numberDiff line change
@@ -968,7 +968,11 @@ public List<Excerpt> getNestedClasses() {
968968
return Collections.unmodifiableList(nestedClasses);
969969
}
970970

971-
/** Sets all property values using the given {@code Datatype} as a template. */
971+
/**
972+
* Copies values from {@code value}, appending to collections, and skipping empty optionals.
973+
*
974+
* @return this {@code Builder} object
975+
*/
972976
public Datatype.Builder mergeFrom(Datatype value) {
973977
Datatype_Builder defaults = new Datatype.Builder();
974978
if (defaults._unsetProperties.contains(Property.TYPE)
@@ -1036,8 +1040,10 @@ public Datatype.Builder mergeFrom(Datatype value) {
10361040
}
10371041

10381042
/**
1039-
* Copies values from the given {@code Builder}. Does not affect any properties not set on the
1040-
* input.
1043+
* Copies values from {@code template}, appending to collections, and skipping empty optionals and
1044+
* unset properties.
1045+
*
1046+
* @return this {@code Builder} object
10411047
*/
10421048
public Datatype.Builder mergeFrom(Datatype.Builder template) {
10431049
// Upcast to access private fields; otherwise, oddly, we get an access violation.
@@ -1107,7 +1113,11 @@ public Datatype.Builder mergeFrom(Datatype.Builder template) {
11071113
return (Datatype.Builder) this;
11081114
}
11091115

1110-
/** Resets the state of this builder. */
1116+
/**
1117+
* Resets the state of this builder.
1118+
*
1119+
* @return this {@code Builder} object
1120+
*/
11111121
public Datatype.Builder clear() {
11121122
Datatype_Builder defaults = new Datatype.Builder();
11131123
type = defaults.type;
@@ -1132,7 +1142,7 @@ public Datatype.Builder clear() {
11321142
}
11331143

11341144
/**
1135-
* Returns a newly-created {@link Datatype} based on the contents of the {@code Builder}.
1145+
* Returns a newly-created {@link Datatype} based on the contents of this {@code Builder}.
11361146
*
11371147
* @throws IllegalStateException if any field has not been set
11381148
*/

0 commit comments

Comments
 (0)