JDK-8190313 : javadoc tool documentation should recommend https: instead of http:
  • Type: Bug
  • Component: docs
  • Sub-Component: tools
  • Affected Version: 9
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • Submitted: 2017-10-27
  • Updated: 2018-11-19
  • Resolved: 2018-11-19
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 10
10Fixed
Related Reports
Relates :  
JDK-8190312 - javadoc -link doesn't work with http: -> https: URL redirects
Description
While looking at https://bugs.openjdk.java.net/browse/JDK-8190312 we noticed that:
The javadoc tool recommends http: instead of https:
https://docs.oracle.com/javase/9/tools/javadoc.htm#JSWOR-GUID-9D532574-1CDB-4D30-99F3-A308DCAEE55F
(and http: doesn't actually work with the jdk9 javadoc)

and the same applies to the javadoc.1 files in the jdk10 mercurial repo.

... and of course the internet industry is moving towards https: as the default
Comments
Reviewing the current docs, I see that it discusses http: and file: and does not mention https: At a bare minimum, it should include https: in the list of possible protocols.
19-12-2017
But "program against the implementation" is exactly the point I was trying to make, rather than advising people to blindly use https: when there is no guarantee that the server providing the API supports https. Let's try a new round of summary: 1. If you're publishing an API, we recommend that you publish the docs via https: if that is an option. 2. If you're referencing an API, you should link to the actual URL by which the docs are available. And note, javadoc will not follow automatic redirect redirects from http: to https: when looking for the info it needs to link to the API.
19-12-2017
> If a user is creating docs and wants to link to some other API, if that API is published via https:, then the link options should use https: That's good advice in practice, BUT it's a little like saying to program against the implementation instead of the public interface. If docs say to use http: then that "must" be the best thing to use for external links.
19-12-2017
A more cautionary change of advice would be to use what the target documentation provides. If a user is creating docs and wants to link to some other API, if that API is published via https:, then the link options should use https:. If that API is published with http:, then it is OK for the link options to use http:
19-12-2017
It seems like Oracle (like other tech companies) has switched entirely to preferring https: over http: with redirects in place for http: but those redirects don't always work and __ALL__ the documentation pointing at http: needs to be audited and perhaps modified to point to https: instead.
31-10-2017
Docs should be updated from http to https in any case, but the fact that http: is actually broken makes it more urgent.
27-10-2017