search

aws / aws-sdk-java-v2

The official AWS SDK for Java - Version 2
Apache License 2.0
2.2k stars 853 forks source link

Broken external links in Javadoc artifacts in Maven Central #2241

Open lbruun opened 3 years ago

lbruun commented 3 years ago

The links from the per-module Javadoc provided in Maven Central into the centrally hosted API docs are broken.

Description of bug

External Links from the Javadoc published in Maven Central point to https://aws.amazon.com/sdkforjava/apidocs but no Javadoc lives there.

Expected Behavior

Correct link.

Current Behavior

Reason for problem: The Maven Javadoc Plugin by default uses ${project.url} value but this value is https://aws.amazon.com/sdkforjava. The Plugin will by convention expect to find Javadoc at the subpath /apidocs of this URL.

Possible Solution

Changing the project's URL, i.e. <url>....</url> value, in all POM files may not be the way to go solely to make the Maven Javadoc Plugin happy. Perhaps an URL redirect would be the easiest solution? Meaning having the aws.amazon.com website redirect requests for https://aws.amazon.com/sdkforjava/apidocs to https://sdk.amazonaws.com/java/api/latest/.

Another option might be to set links configuration value explicitly for the Maven Javadoc Plugin.

Context

Verified as a problem on v2.15.26, but I suspect the problem exist for any version.

debora-ito commented 3 years ago

@lbruun thank you for reaching out. Can you show exactly where are the broken links?

lbruun commented 3 years ago

@debora-ito The incorrect links are literally all over the Javadoc. I would say there are thousands of them. Whenever there's a link to another SDK module.

In the following I show this the problem the old school way (i.e. without an IDE) and with a concrete example.

  1. Download Javadoc bundle for a SDK service from Maven Central. You can use any service to showcase the problem, but in this example I use the ec2 service and I use the latest version as of today, v2.15.66. So the URL to download becomes: https://repo1.maven.org/maven2/software/amazon/awssdk/ec2/2.15.66/ec2-2.15.66-javadoc.jar

  2. Unzip the JAR onto your harddisk and from that content open the file "index.html".

  3. Now you need to find any link which points from this module (ec2) to another SDK module. All such links will be broken. There will by nature be many Javadoc links from the given service module (in this case ec2) into the SDK's core module. For example, for ec2 service, you can browse the interface Ec2AsyncClientBuilder which inherits from interface SdkAsyncClientBilder in core module but you'll notice the link is broken. Here is what it looks like:

2021-01-16 07_56_49-AWS Java SDK __ Services __ Amazon EC2 2 15 66 API — Mozilla Firefox

debora-ito commented 3 years ago

Got it, thank you. I don't know where the javadoc should point to when the structure is in another module. I'll research.

lbruun commented 3 years ago

@debora-ito. It should point to something centrally hosted, e.g. https://sdk.amazonaws.com/java/api/latest/. My personal opinion is - as indicated under "Possible Solutions" - that it is easiest solved with a HTTP redirect implemented on the webserver. But I would guess there are many ways of solving it. How does the SDK-v1 work in this respect?