apache / apache/maven-javadoc-plugin
`detectLinks` default algorithm is practically broken — flexibility needed!
- 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