Skip to content

Commit f909d40

Browse files
jyeminjyemin
authored
Add missing Javadoc (#845)
The Javadoc comments on the private fields are necessary for any public `Serializable` class, which means that the private fields are included in the serialized form page of the generated Javadoc. JAVA-4430
1 parent 9ecb895 commit f909d40

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

54 files changed

+530
-15
lines changed

‎bson/src/main/org/bson/AbstractBsonReader.java

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -771,21 +771,37 @@ private void setStateOnEnd() {
771771
}
772772
}
773773

774+
/**
775+
* An implementation of {@code BsonReaderMark}.
776+
*/
774777
protected class Mark implements BsonReaderMark {
775778
private final State state;
776779
private final Context parentContext;
777780
private final BsonContextType contextType;
778781
private final BsonType currentBsonType;
779782
private final String currentName;
780783

784+
/**
785+
* Gets the parent context.
786+
*
787+
* @return the parent context
788+
*/
781789
protected Context getParentContext() {
782790
return parentContext;
783791
}
784792

793+
/**
794+
* Gets the context type.
795+
*
796+
* @return the context type
797+
*/
785798
protected BsonContextType getContextType() {
786799
return contextType;
787800
}
788801

802+
/**
803+
* Construct an instance.
804+
*/
789805
protected Mark() {
790806
state = AbstractBsonReader.this.state;
791807
parentContext = AbstractBsonReader.this.context.parentContext;
@@ -794,6 +810,7 @@ protected Mark() {
794810
currentName = AbstractBsonReader.this.currentName;
795811
}
796812

813+
@Override
797814
public void reset() {
798815
AbstractBsonReader.this.state = state;
799816
AbstractBsonReader.this.currentBsonType = currentBsonType;

‎bson/src/main/org/bson/BSONException.java

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818

1919
/**
2020
* A general runtime exception raised in BSON processing.
21+
* @serial exclude
2122
*/
2223
public class BSONException extends RuntimeException {
2324

‎bson/src/main/org/bson/BsonBinaryReader.java

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -394,24 +394,35 @@ public BsonReaderMark getMark() {
394394
return new Mark();
395395
}
396396

397+
/**
398+
* An implementation of {@code AbstractBsonReader.Mark}.
399+
*/
397400
protected class Mark extends AbstractBsonReader.Mark {
398401
private final int startPosition;
399402
private final int size;
400403
private final BsonInputMark bsonInputMark;
401404

405+
/**
406+
* Construct an instance.
407+
*/
402408
protected Mark() {
403409
super();
404410
startPosition = BsonBinaryReader.this.getContext().startPosition;
405411
size = BsonBinaryReader.this.getContext().size;
406412
bsonInputMark = BsonBinaryReader.this.bsonInput.getMark(Integer.MAX_VALUE);
407413
}
408414

415+
@Override
409416
public void reset() {
410417
super.reset();
411418
bsonInputMark.reset();
412419
BsonBinaryReader.this.setContext(new Context((Context) getParentContext(), getContextType(), startPosition, size));
413420
}
414421
}
422+
423+
/**
424+
* An implementation of {@code AbstractBsonReader.Context}.
425+
*/
415426
protected class Context extends AbstractBsonReader.Context {
416427
private final int startPosition;
417428
private final int size;

‎bson/src/main/org/bson/BsonBinaryWriter.java

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -420,6 +420,9 @@ private void validateSize(final int size) {
420420
}
421421
}
422422

423+
/**
424+
* An implementation of {@code AbstractBsonWriter.Context}.
425+
*/
423426
protected class Context extends AbstractBsonWriter.Context {
424427
private final int startPosition;
425428
private int index; // used when contextType is an array
@@ -458,6 +461,9 @@ public Context copy() {
458461
}
459462
}
460463

464+
/**
465+
* An implementation of {@code AbstractBsonWriter.Mark}.
466+
*/
461467
protected class Mark extends AbstractBsonWriter.Mark {
462468
private final int position;
463469

‎bson/src/main/org/bson/BsonBoolean.java

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,14 @@ public final class BsonBoolean extends BsonValue implements Comparable<BsonBoole
2525

2626
private final boolean value;
2727

28+
/**
29+
* The true value.
30+
*/
2831
public static final BsonBoolean TRUE = new BsonBoolean(true);
2932

33+
/**
34+
* The false value.
35+
*/
3036
public static final BsonBoolean FALSE = new BsonBoolean(false);
3137

3238
/**

‎bson/src/main/org/bson/BsonDocument.java

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,9 @@
4949
public class BsonDocument extends BsonValue implements Map<String, BsonValue>, Cloneable, Bson, Serializable {
5050
private static final long serialVersionUID = 1L;
5151

52+
/**
53+
* The underlying map.
54+
*/
5255
private final Map<String, BsonValue> map;
5356

5457
/**
@@ -882,12 +885,29 @@ private void throwIfKeyAbsent(final Object key) {
882885
}
883886
}
884887

885-
// see https://docs.oracle.com/javase/6/docs/platform/serialization/spec/output.html
888+
/**
889+
* Write the replacement object.
890+
*
891+
* <p>
892+
* See https://docs.oracle.com/javase/6/docs/platform/serialization/spec/output.html
893+
* </p>
894+
*
895+
* @return a proxy for the document
896+
*/
886897
private Object writeReplace() {
887898
return new SerializationProxy(this);
888899
}
889900

890-
// see https://docs.oracle.com/javase/6/docs/platform/serialization/spec/input.html
901+
/**
902+
* Prevent normal deserialization.
903+
*
904+
* <p>
905+
* See https://docs.oracle.com/javase/6/docs/platform/serialization/spec/input.html
906+
* </p>
907+
*
908+
* @param stream the stream
909+
* @throws InvalidObjectException in all cases
910+
*/
891911
private void readObject(final ObjectInputStream stream) throws InvalidObjectException {
892912
throw new InvalidObjectException("Proxy required");
893913
}

‎bson/src/main/org/bson/BsonDocumentReader.java

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -243,17 +243,25 @@ public BsonReaderMark getMark() {
243243
protected Context getContext() {
244244
return (Context) super.getContext();
245245
}
246+
247+
/**
248+
* An implementation of {@code AbstractBsonReader.Mark}.
249+
*/
246250
protected class Mark extends AbstractBsonReader.Mark {
247251
private final BsonValue currentValue;
248252
private final Context context;
249253

254+
/**
255+
* Construct an instance.
256+
*/
250257
protected Mark() {
251258
super();
252259
currentValue = BsonDocumentReader.this.currentValue;
253260
context = BsonDocumentReader.this.getContext();
254261
context.mark();
255262
}
256263

264+
@Override
257265
public void reset() {
258266
super.reset();
259267
BsonDocumentReader.this.currentValue = currentValue;
@@ -325,28 +333,54 @@ public void remove() {
325333
}
326334
}
327335

336+
/**
337+
* An implementation of {@code AbstractBsonReader.Context}.
338+
*/
328339
protected class Context extends AbstractBsonReader.Context {
329340

330341
private BsonDocumentMarkableIterator<Map.Entry<String, BsonValue>> documentIterator;
331342
private BsonDocumentMarkableIterator<BsonValue> arrayIterator;
332343

344+
/**
345+
* Construct an instance.
346+
*
347+
* @param parentContext the parent context
348+
* @param contextType the context type
349+
* @param array the array context
350+
*/
333351
protected Context(final Context parentContext, final BsonContextType contextType, final BsonArray array) {
334352
super(parentContext, contextType);
335353
arrayIterator = new BsonDocumentMarkableIterator<BsonValue>(array.iterator());
336354
}
337355

356+
/**
357+
* Construct an instance.
358+
*
359+
* @param parentContext the parent context
360+
* @param contextType the context type
361+
* @param document the document context
362+
*/
338363
protected Context(final Context parentContext, final BsonContextType contextType, final BsonDocument document) {
339364
super(parentContext, contextType);
340365
documentIterator = new BsonDocumentMarkableIterator<Map.Entry<String, BsonValue>>(document.entrySet().iterator());
341366
}
342367

368+
/**
369+
* Gets the next element.
370+
*
371+
* @return the next element, which may be null
372+
*/
343373
public Map.Entry<String, BsonValue> getNextElement() {
344374
if (documentIterator.hasNext()) {
345375
return documentIterator.next();
346376
} else {
347377
return null;
348378
}
349379
}
380+
381+
/**
382+
* Create a mark.
383+
*/
350384
protected void mark() {
351385
if (documentIterator != null) {
352386
documentIterator.mark();
@@ -359,6 +393,9 @@ protected void mark() {
359393
}
360394
}
361395

396+
/**
397+
* Reset the context.
398+
*/
362399
protected void reset() {
363400
if (documentIterator != null) {
364401
documentIterator.reset();
@@ -371,6 +408,11 @@ protected void reset() {
371408
}
372409
}
373410

411+
/**
412+
* Gets the next value.
413+
*
414+
* @return the next value, which may be null
415+
*/
374416
public BsonValue getNextValue() {
375417
if (arrayIterator.hasNext()) {
376418
return arrayIterator.next();

‎bson/src/main/org/bson/BsonDocumentWrapper.java

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,10 @@ public final class BsonDocumentWrapper<T> extends BsonDocument {
4141

4242
private final transient T wrappedDocument;
4343
private final transient Encoder<T> encoder;
44+
45+
/**
46+
* The unwrapped document, which may be null
47+
*/
4448
private BsonDocument unwrapped;
4549

4650
/**
@@ -198,12 +202,29 @@ private BsonDocument getUnwrapped() {
198202
return unwrapped;
199203
}
200204

201-
// see https://docs.oracle.com/javase/6/docs/platform/serialization/spec/output.html
205+
/**
206+
* Write the replacement object.
207+
*
208+
* <p>
209+
* See https://docs.oracle.com/javase/6/docs/platform/serialization/spec/output.html
210+
* </p>
211+
*
212+
* @return a proxy for the document
213+
*/
202214
private Object writeReplace() {
203215
return getUnwrapped();
204216
}
205217

206-
// see https://docs.oracle.com/javase/6/docs/platform/serialization/spec/input.html
218+
/**
219+
* Prevent normal deserialization.
220+
*
221+
* <p>
222+
* See https://docs.oracle.com/javase/6/docs/platform/serialization/spec/input.html
223+
* </p>
224+
*
225+
* @param stream the stream
226+
* @throws InvalidObjectException in all cases
227+
*/
207228
private void readObject(final ObjectInputStream stream) throws InvalidObjectException {
208229
throw new InvalidObjectException("Proxy required");
209230
}

‎bson/src/main/org/bson/BsonNull.java

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,9 @@
2323
*/
2424
public final class BsonNull extends BsonValue {
2525

26+
/**
27+
* A singleton instance of the null value.
28+
*/
2629
public static final BsonNull VALUE = new BsonNull();
2730

2831
@Override

‎bson/src/main/org/bson/Document.java

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,9 @@ public class Document implements Map<String, Object>, Serializable, Bson {
6969

7070
private static final long serialVersionUID = 6297731997167536582L;
7171

72+
/**
73+
* The map of keys to values.
74+
*/
7275
private final LinkedHashMap<String, Object> documentAsMap;
7376

7477
/**

0 commit comments

Comments
 (0)