[JAVA-4430] Address javadoc warnings Created: 20/Dec/21  Updated: 28/Oct/23  Resolved: 05/Jan/22

Status: Closed
Project: Java Driver
Component/s: Documentation
Affects Version/s: None
Fix Version/s: 4.5.0

Type: Improvement Priority: Major - P3
Reporter: Jeffrey Yemin Assignee: Jeffrey Yemin
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Documentation Changes: Not Needed

 Description   

Ideally we would be warning free, but currently:

> Task :driver-core:javadoc
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/client/model/BucketGranularity.java:35: warning: no comment
    E12,
    ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/client/model/BucketGranularity.java:39: warning: no comment
    E192,
    ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/client/model/BucketGranularity.java:36: warning: no comment
    E24,
    ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/client/model/BucketGranularity.java:37: warning: no comment
    E48,
    ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/client/model/BucketGranularity.java:34: warning: no comment
    E6,
    ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/client/model/BucketGranularity.java:38: warning: no comment
    E96,
    ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/client/model/BucketGranularity.java:40: warning: no comment
    POWERSOF2;
    ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/client/model/BucketGranularity.java:29: warning: no comment
    R10,
    ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/client/model/BucketGranularity.java:30: warning: no comment
    R20,
    ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/client/model/BucketGranularity.java:31: warning: no comment
    R40,
    ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/client/model/BucketGranularity.java:28: warning: no comment
    R5,
    ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/client/model/BucketGranularity.java:32: warning: no comment
    R80,
    ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/client/model/BucketGranularity.java:33: warning: no comment
    SERIES_125("1-2-5"),
    ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/client/model/vault/DataKeyOptions.java:102: warning: empty <p> tag
     * <p>
       ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/MongoException.java:199: warning: no comment
    protected void addLabels(final Collection<String> labels) {
                   ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/MongoException.java:193: warning: no comment
    protected void addLabels(final BsonArray labels) {
                   ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/MongoNamespace.java:38: warning: no comment
    public static final String COMMAND_COLLECTION_NAME = "$cmd";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/client/model/MongoTimeUnit.java:33: warning: no comment
    DAY("day", true),
    ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/client/model/MongoTimeUnit.java:34: warning: no comment
    HOUR("hour", true),
    ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/client/model/MongoTimeUnit.java:37: warning: no comment
    MILLISECOND("millisecond", true);
    ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/client/model/MongoTimeUnit.java:35: warning: no comment
    MINUTE("minute", true),
    ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/client/model/MongoTimeUnit.java:31: warning: no comment
    MONTH("month", false),
    ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/client/model/MongoTimeUnit.java:30: warning: no comment
    QUARTER("quarter", false),
    ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/client/model/MongoTimeUnit.java:36: warning: no comment
    SECOND("second", true),
    ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/client/model/MongoTimeUnit.java:32: warning: no comment
    WEEK("week", true),
    ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/client/model/MongoTimeUnit.java:29: warning: no comment
    YEAR("year", false),
    ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/ReadPreference.java:157: warning: no comment
    protected abstract List<ServerDescription> chooseForNonReplicaSet(ClusterDescription clusterDescription);
                                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/ReadPreference.java:159: warning: no comment
    protected abstract List<ServerDescription> chooseForReplicaSet(ClusterDescription clusterDescription);
                                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/TaggableReadPreference.java:208: warning: no comment
    protected static ClusterDescription copyClusterDescription(final ClusterDescription clusterDescription,
                                        ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/TaggableReadPreference.java:217: warning: no comment
    protected List<ServerDescription> selectFreshServers(final ClusterDescription clusterDescription,
                                      ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/BasicDBList.java:61: warning: no comment
    private boolean _isPartialObject;
                    ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/BasicDBObject.java:68: warning: no comment
    private boolean isPartialObject;
                    ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/DBRef.java:37: warning: no comment
    private final String collectionName;
                         ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/DBRef.java:38: warning: no comment
    private final String databaseName;
                         ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/DBRef.java:36: warning: no comment
    private final Object id;
                         ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/MongoBulkWriteException.java:38: warning: no comment
    private final List<BulkWriteError> errors;
                                       ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/MongoBulkWriteException.java:39: warning: no comment
    private final ServerAddress serverAddress;
                                ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/MongoBulkWriteException.java:40: warning: no comment
    private final WriteConcernError writeConcernError;
                                    ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/MongoBulkWriteException.java:37: warning: no comment
    private final BulkWriteResult writeResult;
                                  ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/MongoCommandException.java:39: warning: no comment
    private final BsonDocument response;
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/MongoCursorNotFoundException.java:28: warning: no comment
    private final long cursorId;
                       ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/MongoCursorNotFoundException.java:29: warning: no comment
    private final ServerAddress serverAddress;
                                ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/MongoException.java:54: warning: no comment
    private final int code;
                      ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/MongoException.java:55: warning: no comment
    private final Set<String> errorLabels = new HashSet<String>();
                              ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/MongoIncompatibleDriverException.java:29: warning: no comment
    private ClusterDescription clusterDescription;
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/MongoQueryException.java:28: warning: no comment
    private final String errorMessage;
                         ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/MongoSecurityException.java:27: warning: no comment
    private final MongoCredential credential;
                                  ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/MongoServerException.java:26: warning: no comment
    private final ServerAddress serverAddress;
                                ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/MongoSocketException.java:28: warning: no comment
    private final ServerAddress serverAddress;
                                ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/MongoWriteConcernException.java:34: warning: no comment
    private final WriteConcernError writeConcernError;
                                    ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/MongoWriteConcernException.java:35: warning: no comment
    private final WriteConcernResult writeConcernResult;
                                     ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/MongoWriteException.java:28: warning: no comment
    private final WriteError error;
                             ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/ServerAddress.java:36: warning: no comment
    private final String host;
                         ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/ServerAddress.java:37: warning: no comment
    private final int port;
                      ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/ServerCursor.java:35: warning: no comment
    private final ServerAddress address;
                                ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/ServerCursor.java:34: warning: no comment
    private final long id;
                       ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/WriteConcern.java:77: warning: no comment
    private final Boolean journal;
                          ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/WriteConcern.java:73: warning: no comment
    private final Object w;
                         ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/WriteConcern.java:75: warning: no comment
    private final Integer wTimeoutMS;
                          ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/WriteConcernException.java:48: warning: no comment
    private final BsonDocument response;
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-core/src/main/com/mongodb/WriteConcernException.java:47: warning: no comment
    private final WriteConcernResult writeConcernResult;
                                     ^
61 warnings
 
> Task :driver-legacy:javadoc
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/DBCollection.java:128: warning: no comment
    public static final String ID_FIELD_NAME = "_id";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/DefaultDBCallback.java:77: warning: no comment
    public static final DBCallbackFactory FACTORY = new DBCallbackFactory() {
                                          ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/DefaultDBDecoder.java:53: warning: no comment
    public static final DBDecoderFactory FACTORY = new DBDecoderFactory() {
                                         ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/DefaultDBEncoder.java:66: warning: no comment
    public static final DBEncoderFactory FACTORY = new DBEncoderFactory() {
                                         ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/LazyDBDecoder.java:58: warning: no comment
    public static final DBDecoderFactory FACTORY = new DBDecoderFactory() {
                                         ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/QueryOperators.java:37: warning: no comment
    public static final String ALL = "$all";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/QueryOperators.java:26: warning: no comment
    public static final String AND = "$and";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/QueryOperators.java:52: warning: no comment
    public static final String BOX = "$box";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/QueryOperators.java:53: warning: no comment
    public static final String CENTER = "$center";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/QueryOperators.java:55: warning: no comment
    public static final String CENTER_SPHERE = "$centerSphere";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/QueryOperators.java:40: warning: no comment
    public static final String ELEM_MATCH = "$elemMatch";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/QueryOperators.java:39: warning: no comment
    public static final String EXISTS = "$exists";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/QueryOperators.java:28: warning: no comment
    public static final String GT = "$gt";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/QueryOperators.java:29: warning: no comment
    public static final String GTE = "$gte";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/QueryOperators.java:34: warning: no comment
    public static final String IN = "$in";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/QueryOperators.java:63: warning: no comment
    public static final String LANGUAGE = "$language";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/QueryOperators.java:30: warning: no comment
    public static final String LT = "$lt";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/QueryOperators.java:31: warning: no comment
    public static final String LTE = "$lte";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/QueryOperators.java:57: warning: no comment
    public static final String MAX_DISTANCE = "$maxDistance";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/QueryOperators.java:36: warning: no comment
    public static final String MOD = "$mod";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/QueryOperators.java:33: warning: no comment
    public static final String NE = "$ne";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/QueryOperators.java:50: warning: no comment
    public static final String NEAR = "$near";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/QueryOperators.java:51: warning: no comment
    public static final String NEAR_SPHERE = "$nearSphere";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/QueryOperators.java:35: warning: no comment
    public static final String NIN = "$nin";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/QueryOperators.java:44: warning: no comment
    public static final String NOR = "$nor";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/QueryOperators.java:46: warning: no comment
    public static final String NOT = "$not";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/QueryOperators.java:25: warning: no comment
    public static final String OR = "$or";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/QueryOperators.java:54: warning: no comment
    public static final String POLYGON = "$polygon";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/QueryOperators.java:62: warning: no comment
    public static final String SEARCH = "$search";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/QueryOperators.java:38: warning: no comment
    public static final String SIZE = "$size";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/QueryOperators.java:61: warning: no comment
    public static final String TEXT = "$text";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/QueryOperators.java:45: warning: no comment
    public static final String TYPE = "$type";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/QueryOperators.java:58: warning: no comment
    public static final String UNIQUE_DOCS = "$uniqueDocs";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/QueryOperators.java:43: warning: no comment
    public static final String WHERE = "$where";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/QueryOperators.java:49: warning: no comment
    public static final String WITHIN = "$within";
                               ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/BulkWriteException.java:34: warning: no comment
    private final ServerAddress serverAddress;
                                ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/BulkWriteException.java:35: warning: no comment
    private final WriteConcernError writeConcernError;
                                    ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/BulkWriteException.java:33: warning: no comment
    private final List<BulkWriteError> writeErrors;
                                       ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/BulkWriteException.java:32: warning: no comment
    private final BulkWriteResult writeResult;
                                  ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/CommandResult.java:33: warning: no comment
    private final ServerAddress address;
                                ^
/Users/jeff.yemin/git/mongo-java-driver/driver-legacy/src/main/com/mongodb/CommandResult.java:32: warning: no comment
    private final BsonDocument response;
                               ^
41 warnings



 Comments   
Comment by Githook User [ 05/Jan/22 ]

Author:

{'name': 'Jeff Yemin', 'email': 'jeff.yemin@mongodb.com', 'username': 'jyemin'}

Message: 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
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/f909d407de8bf1c5c954afa4bf0ad846302a3bd4

Comment by Jeffrey Yemin [ 21/Dec/21 ]

I think the warnings for private fields is for any class which is Serializable. See https://bugs.openjdk.java.net/browse/JDK-8251200.

The warning can be suppressed by adding @serial exclude to the class Javadoc. Maybe we should do that for all the exception types, at least.

Generated at Thu Feb 08 09:02:03 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.