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

Commit bc437ad

Browse files
alicederynalicederyn
authored
#406 Improve JavaDoc for core methods
2 parents 75479d4 + 0bd85a9 commit bc437ad

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)