[JAVA-1391] Complete Javadoc for driver-core Created: 19/Aug/14  Updated: 30/Jan/15  Resolved: 07/Oct/14

Status: Closed
Project: Java Driver
Component/s: API, Documentation
Affects Version/s: None
Fix Version/s: 3.0.0

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

Attachments: File driver-core-javadoc-errors.rtf    

 Description   

Ensure that all public methods in all public classes in driver-core have proper Javadoc



 Comments   
Comment by Githook User [ 30/Jan/15 ]

Author:

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

Message: Completed Javadoc for the driver-core module of almost all public classes and public or protected members.

JAVA-1391
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/0c5b1a2f6980683454f18ea94cd5b01eab4bc37f

Comment by Githook User [ 30/Jan/15 ]

Author:

{u'username': u'trishagee', u'name': u'Trisha Gee', u'email': u'trishagee@github.com'}

Message: JAVA-1391 Javadoc for com.mongodb.codecs package (added missing Javadoc). Also some tiny tidy ups, like making methods private and removing @SuppressWarnings where possible.
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/8c6585f7be59daaf47b8a5e290f5bb8ed037f78f

Comment by Githook User [ 30/Jan/15 ]

Author:

{u'username': u'trishagee', u'name': u'Trisha Gee', u'email': u'trishagee@github.com'}

Message: [JAVA-1391/2/3] Fixed Javadoc so it builds under Java 8.
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/eabdf54001b696882f0ad1f10e7aba4461f1e919

Comment by Githook User [ 30/Jan/15 ]

Author:

{u'username': u'trishagee', u'name': u'Trisha Gee', u'email': u'trishagee@github.com'}

Message: JAVA-1391 Javadoc for com.mongodb.binding & com.mongodb.connection packages (added missing Javadoc).
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/1fb1e708a9310c6a814a8b9f14154c9879380385

Comment by Githook User [ 30/Jan/15 ]

Author:

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

Message: JAVA-1391: Javadoc for public classes that should not be considered part of the public API.
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/bff861c5f18a950b7233286080eb0f2ea8d4ba6b

Comment by Githook User [ 30/Jan/15 ]

Author:

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

Message: JAVA-1391: Javadoc for NativeAuthenticationHelper
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/cbc44a8e9544df1238fc19329034534ff49eb437

Comment by Githook User [ 30/Jan/15 ]

Author:

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

Message: JAVA-1391: Javadoc for AsyncCompletionHandler
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/8e241b9924b5e8c49a4d6bf903cdefac39f0f37e

Comment by Githook User [ 30/Jan/15 ]

Author:

{u'username': u'trishagee', u'name': u'Trisha Gee', u'email': u'trisha.gee@10gen.com'}

Message: Merge pull request #242 from trishagee/JAVA-1391

JAVA-1391: Javadoc for driver-core, first batch of documentation
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/ce5e910bf2e58256e99c7f2af8b384038b4d2901

Comment by Githook User [ 30/Jan/15 ]

Author:

{u'username': u'trishagee', u'name': u'Trisha Gee', u'email': u'trisha.gee@10gen.com'}

Message: Merge pull request #242 from trishagee/JAVA-1391

JAVA-1391: Javadoc for driver-core, first batch of documentation
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/ce5e910bf2e58256e99c7f2af8b384038b4d2901

Comment by Githook User [ 30/Jan/15 ]

Author:

{u'username': u'trishagee', u'name': u'Trisha Gee', u'email': u'trishagee@github.com'}

Message: JAVA-1391 Fixed groovy for new codenarc settings
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/1b07dadf6b9378376bde4e3b4311f8e9d3da16e0

Comment by Githook User [ 30/Jan/15 ]

Author:

{u'username': u'trishagee', u'name': u'Trisha Gee', u'email': u'trishagee@github.com'}

Message: JAVA-1391 Fixed all errors for generating Javadoc using Java 8, so Java 8 can now be used to build; in the classes that were touched by this, added missing Javadoc and tried to apply standard HTML formatting to more descriptive sections (e.g. lists instead of tables).
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/5edb10c4a0382210f6424338132673e2b4e2d647

Comment by Githook User [ 30/Jan/15 ]

Author:

{u'username': u'trishagee', u'name': u'Trisha Gee', u'email': u'trishagee@github.com'}

Message: JAVA-1391 Fixes from Ross's suggestions.
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/d0aa9e507154b88a159d96de50651a05158e51d7

Comment by Githook User [ 30/Jan/15 ]

Author:

{u'username': u'trishagee', u'name': u'Trisha Gee', u'email': u'trishagee@github.com'}

Message: JAVA-1391 Applying suggestions from pull request review.
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/2dc27ca76e79e3ccbc16cbc6fd0ba287a641576a

Comment by Githook User [ 30/Jan/15 ]

Author:

{u'username': u'trishagee', u'name': u'Trisha Gee', u'email': u'trishagee@github.com'}

Message: JAVA-1391 Updating Javadoc for connection package to pass checkstyle check for Javadoc on public classes & methods. Added @since tags where the right version was known.
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/0269708a92272779fde1454316a1d5646cfea5c6

Comment by Githook User [ 30/Jan/15 ]

Author:

{u'username': u'trishagee', u'name': u'Trisha Gee', u'email': u'trishagee@github.com'}

Message: JAVA-1391 Updating Javadoc for connection package to pass checkstyle check for Javadoc on public classes & methods. Added @since tags where the right version was known. Applied consistency around use of final keyword according to our agreed standards.
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/4c66f6416e9b7fab731f2e8e50dd0809d47ecd61

Comment by Githook User [ 30/Jan/15 ]

Author:

{u'username': u'trishagee', u'name': u'Trisha Gee', u'email': u'trishagee@github.com'}

Message: JAVA-1391 Updating Javadoc to a) pass checkstyle check for Javadoc on public classes & methods and b) not fail under Java 8 Javadoc generation. Added package-info.java for packages that were touched. Added @since tags where the right version was known.
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/351f5d1ed836d450ae5fd34f82127a7240f08d9f

Comment by Githook User [ 30/Jan/15 ]

Author:

{u'username': u'trishagee', u'name': u'Trisha Gee', u'email': u'trishagee@github.com'}

Message: JAVA-1391 Updating Javadoc to a) pass checkstyle check for Javadoc on public classes & methods and b) not fail under Java 8 Javadoc generation. Added a test to document WriteConcern throwing ClassCastException under certain circumstances
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/21cb3943f6975cca103b069469e0803f587a279b

Comment by Trisha Gee [ 02/Oct/14 ]

This is still not complete. Checkstyle is showing the following missing documentation:

com/mongodb/assertions/Assertions.java:66:5: Missing a Javadoc comment.
org/mongodb/Document.java:76:8: Unable to get class information for @throws tag 'org.bson.json.JsonParseException'.
org/mongodb/Document.java:76:8: Unused @throws tag for 'org.bson.json.JsonParseException'.

When all the documentation has been completed, line 25 from checkstyle-exclude.xml can be removed and the "check" task should complete successfully.

Comment by Githook User [ 29/Sep/14 ]

Author:

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

Message: Completed Javadoc for the driver-core module of almost all public classes and public or protected members.

JAVA-1391
Branch: 3.0.x
https://github.com/mongodb/mongo-java-driver/commit/0c5b1a2f6980683454f18ea94cd5b01eab4bc37f

Comment by Githook User [ 12/Sep/14 ]

Author:

{u'username': u'trishagee', u'name': u'Trisha Gee', u'email': u'trishagee@github.com'}

Message: JAVA-1391 Javadoc for com.mongodb.codecs package (added missing Javadoc). Also some tiny tidy ups, like making methods private and removing @SuppressWarnings where possible.
Branch: 3.0.x
https://github.com/mongodb/mongo-java-driver/commit/8c6585f7be59daaf47b8a5e290f5bb8ed037f78f

Comment by Githook User [ 10/Sep/14 ]

Author:

{u'username': u'trishagee', u'name': u'Trisha Gee', u'email': u'trishagee@github.com'}

Message: [JAVA-1391/2/3] Fixed Javadoc so it builds under Java 8.
Branch: 3.0.x
https://github.com/mongodb/mongo-java-driver/commit/eabdf54001b696882f0ad1f10e7aba4461f1e919

Comment by Githook User [ 05/Sep/14 ]

Author:

{u'username': u'trishagee', u'name': u'Trisha Gee', u'email': u'trishagee@github.com'}

Message: JAVA-1391 Javadoc for com.mongodb.binding & com.mongodb.connection packages (added missing Javadoc).
Branch: 3.0.x
https://github.com/mongodb/mongo-java-driver/commit/1fb1e708a9310c6a814a8b9f14154c9879380385

Comment by Githook User [ 05/Sep/14 ]

Author:

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

Message: JAVA-1391: Javadoc for public classes that should not be considered part of the public API.
Branch: crud
https://github.com/mongodb/mongo-java-driver/commit/efd4153f6753b31dd30481c60edac944dbffdf84

Comment by Githook User [ 05/Sep/14 ]

Author:

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

Message: JAVA-1391: Javadoc for NativeAuthenticationHelper
Branch: crud
https://github.com/mongodb/mongo-java-driver/commit/512118b4772e367de67bd284ef71cc037bfae284

Comment by Githook User [ 05/Sep/14 ]

Author:

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

Message: JAVA-1391: Javadoc for AsyncCompletionHandler
Branch: crud
https://github.com/mongodb/mongo-java-driver/commit/a63d6aafa2af3aa300ee147a9e87e3eff75e5669

Comment by Githook User [ 04/Sep/14 ]

Author:

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

Message: JAVA-1391: Javadoc for public classes that should not be considered part of the public API.
Branch: 3.0.x
https://github.com/mongodb/mongo-java-driver/commit/bff861c5f18a950b7233286080eb0f2ea8d4ba6b

Comment by Githook User [ 04/Sep/14 ]

Author:

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

Message: JAVA-1391: Javadoc for NativeAuthenticationHelper
Branch: 3.0.x
https://github.com/mongodb/mongo-java-driver/commit/cbc44a8e9544df1238fc19329034534ff49eb437

Comment by Githook User [ 04/Sep/14 ]

Author:

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

Message: JAVA-1391: Javadoc for AsyncCompletionHandler
Branch: 3.0.x
https://github.com/mongodb/mongo-java-driver/commit/8e241b9924b5e8c49a4d6bf903cdefac39f0f37e

Comment by Githook User [ 03/Sep/14 ]

Author:

{u'username': u'trishagee', u'name': u'Trisha Gee', u'email': u'trisha.gee@10gen.com'}

Message: Merge pull request #242 from trishagee/JAVA-1391

JAVA-1391: Javadoc for driver-core, first batch of documentation
Branch: 3.0.x
https://github.com/mongodb/mongo-java-driver/commit/ce5e910bf2e58256e99c7f2af8b384038b4d2901

Comment by Githook User [ 03/Sep/14 ]

Author:

{u'username': u'trishagee', u'name': u'Trisha Gee', u'email': u'trisha.gee@10gen.com'}

Message: Merge pull request #242 from trishagee/JAVA-1391

JAVA-1391: Javadoc for driver-core, first batch of documentation
Branch: 3.0.x
https://github.com/mongodb/mongo-java-driver/commit/ce5e910bf2e58256e99c7f2af8b384038b4d2901

Comment by Githook User [ 03/Sep/14 ]

Author:

{u'username': u'trishagee', u'name': u'Trisha Gee', u'email': u'trishagee@github.com'}

Message: JAVA-1391 Fixed groovy for new codenarc settings
Branch: 3.0.x
https://github.com/mongodb/mongo-java-driver/commit/1b07dadf6b9378376bde4e3b4311f8e9d3da16e0

Comment by Githook User [ 03/Sep/14 ]

Author:

{u'username': u'trishagee', u'name': u'Trisha Gee', u'email': u'trishagee@github.com'}

Message: JAVA-1391 Fixed all errors for generating Javadoc using Java 8, so Java 8 can now be used to build; in the classes that were touched by this, added missing Javadoc and tried to apply standard HTML formatting to more descriptive sections (e.g. lists instead of tables).
Branch: 3.0.x
https://github.com/mongodb/mongo-java-driver/commit/5edb10c4a0382210f6424338132673e2b4e2d647

Comment by Githook User [ 03/Sep/14 ]

Author:

{u'username': u'trishagee', u'name': u'Trisha Gee', u'email': u'trishagee@github.com'}

Message: JAVA-1391 Fixes from Ross's suggestions.
Branch: 3.0.x
https://github.com/mongodb/mongo-java-driver/commit/d0aa9e507154b88a159d96de50651a05158e51d7

Comment by Githook User [ 03/Sep/14 ]

Author:

{u'username': u'trishagee', u'name': u'Trisha Gee', u'email': u'trishagee@github.com'}

Message: JAVA-1391 Applying suggestions from pull request review.
Branch: 3.0.x
https://github.com/mongodb/mongo-java-driver/commit/2dc27ca76e79e3ccbc16cbc6fd0ba287a641576a

Comment by Githook User [ 03/Sep/14 ]

Author:

{u'username': u'trishagee', u'name': u'Trisha Gee', u'email': u'trishagee@github.com'}

Message: JAVA-1391 Updating Javadoc for connection package to pass checkstyle check for Javadoc on public classes & methods. Added @since tags where the right version was known.
Branch: 3.0.x
https://github.com/mongodb/mongo-java-driver/commit/0269708a92272779fde1454316a1d5646cfea5c6

Comment by Githook User [ 03/Sep/14 ]

Author:

{u'username': u'trishagee', u'name': u'Trisha Gee', u'email': u'trishagee@github.com'}

Message: JAVA-1391 Updating Javadoc for connection package to pass checkstyle check for Javadoc on public classes & methods. Added @since tags where the right version was known. Applied consistency around use of final keyword according to our agreed standards.
Branch: 3.0.x
https://github.com/mongodb/mongo-java-driver/commit/4c66f6416e9b7fab731f2e8e50dd0809d47ecd61

Comment by Githook User [ 03/Sep/14 ]

Author:

{u'username': u'trishagee', u'name': u'Trisha Gee', u'email': u'trishagee@github.com'}

Message: JAVA-1391 Updating Javadoc to a) pass checkstyle check for Javadoc on public classes & methods and b) not fail under Java 8 Javadoc generation. Added package-info.java for packages that were touched. Added @since tags where the right version was known.
Branch: 3.0.x
https://github.com/mongodb/mongo-java-driver/commit/351f5d1ed836d450ae5fd34f82127a7240f08d9f

Comment by Githook User [ 03/Sep/14 ]

Author:

{u'username': u'trishagee', u'name': u'Trisha Gee', u'email': u'trishagee@github.com'}

Message: JAVA-1391 Updating Javadoc to a) pass checkstyle check for Javadoc on public classes & methods and b) not fail under Java 8 Javadoc generation. Added a test to document WriteConcern throwing ClassCastException under certain circumstances
Branch: 3.0.x
https://github.com/mongodb/mongo-java-driver/commit/21cb3943f6975cca103b069469e0803f587a279b

Comment by Trisha Gee [ 26/Aug/14 ]

First pass of running the checkstyle rule to enforce Javadoc on public methods and classes in driver-core:

559 Errors

Mostly missing Javadoc, with some errors on existing javadoc (report attached).

Also, running Javadoc with Java 8 gives the following:
45 errors
47 warnings

There's not much overlap between the 531 errors in the first case and the 45 errors in the second, since Java 8 introduces new strict HTML checking.

Generated at Thu Feb 08 08:54:30 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.