[JAVA-3819] Include package-list when deploying javadoc Created: 18/Aug/20  Updated: 27/Oct/23  Resolved: 07/Sep/20

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

Type: Improvement Priority: Minor - P4
Reporter: Daniel John Gomez Assignee: Ross Lawley
Resolution: Works as Designed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Attachments: PNG File Screen Shot 2020-08-18 at 3.41.06 PM.png    

 Description   

I'm trying to reference MongoDB java driver classes' javadoc from my project which is done using maven-javadoc-plugin. It was working fine in v3 of the driver. Links do not show up when I upgraded to v4.

Upon investigation, the issue seems to be v4 of the java driver docs do not have the package-list }}file. This is required by the plugin and part of the javadoc specification Only versions 3.4-3.10 have the {{package-list file (checked on https://github.com/mongodb/mongo-java-driver/find/gh-pages).

I tried building the docs using gradle docs and the file is there so I think it's just being excluded when it's deployed to Github pages.



 Comments   
Comment by Daniel John Gomez [ 10/Sep/20 ]

By the way, I also tried updating our maven javadoc plugin to 3.2.0 but it didn't work.

Comment by Daniel John Gomez [ 10/Sep/20 ]

Hi Ross,

I see. This seems to be more of a JDK issue. The javadoc cli tool (to which maven-javadoc-plugin delegates to) is still expecting package-list to reference external links correctly (reference). 

I found this ticket on OpenJDK which describes the issue but is only fixed on Java 12.

I wonder if it's alright on your end to copy the element-list to package-list manually as a workaround just like how Gradle handled this issue on https://github.com/gradle/gradle/pull/8193

Comment by Ross Lawley [ 07/Sep/20 ]

Hi djgomez23@gmail.com,

The javadocs generated by versions 3.11+ use Java 11 which doesn't publish a package-list but does publish a elements-list file instead.

Happily the error has been reported and fixed in the maven-javadoc plugin: MJAVADOC-534

Ross

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