apache / apache/maven-javadoc-plugin

`detectLinks` default algorithm is practically broken — flexibility needed!

Open
#1,293 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Java
Stars
107
Forks
116
Avg merge
1d 10h
Merged PRs (30d)
16

Description

### Current Behavior

The detection algorithm behind the [`detectLinks` parameter](https://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html#detectLinks), used to resolve cross-reference Javadoc links for project dependencies, is based on the **default Maven convention** `${project.url}/apidocs`.

### Problem

In reality, *the overwhelming majority of published artifacts do NOT follow such convention*; rather, they typically rely on custom locations or, more commonly, on hosting services like .

As a consequence, *most cross-reference Javadoc links do NOT work out of the box*: they require tedious manual configuration via `dependencyLinks`.

### Proposed Behavior

What's the point of carrying on with a broken algorithm that most of the times doesn't suit real needs? *Instead of forcing venerable dead conventions onto users, it would be much more useful if the detection algorithm dealt with the complexity of the real world*.

My proposal is to let users define **base URLs whenever dependency links can be automatically resolved** — for example:

```xml

https://javadoc.io/doc/

```

The resolution will append GAV coordinates to the path:

```
$linkBase/$groupId/$artifactId/$version/
```

For example:

```
https://javadoc.io/doc/net.bytebuddy/byte-buddy/1.18.2/
```

For each dependency, the algorithm will probe the default conventional location, then the specified `linkBases`, until a match is found; to speed things up, the algorithm could cache successful hits.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start from the detectLinks parameter and the existing dependencyLinks behavior described in the issue; the payload names no implementation files or tests. Clarify how configurable linkBases should interact with the default Maven location, GAV path resolution, probing, and caching. Done means an agreed design and implementation plan for automatic cross-reference links.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
build-system
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.