From 790f862e3c7354dce89927be2134da05b9e978a6 Mon Sep 17 00:00:00 2001
From: Jonathan Hefner <jonathan@hefner.pro>
Date: Sun, 16 Nov 2025 09:51:21 -0600
Subject: [PATCH] fix: Enable javadoc generation for modules with OSGi metadata
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

**Problem:**
The javadoc JARs published to Maven Central for `mcp-core` and other modules
contain no HTML documentation (only `META-INF` directory structure). This
prevents javadoc.io from automatically displaying API documentation for these
modules.

**Root cause:**
The `bnd-maven-plugin` adds an `Automatic-Module-Name` entry to the JAR manifest
for OSGi compatibility. When `maven-javadoc-plugin` detects this manifest entry,
it switches from traditional classpath mode to JPMS (Java Platform Module
System) module mode. In module mode, javadoc uses different command-line
arguments (`--module-path` and `--patch-module` instead of `-sourcepath`), which
fail to generate HTML output for automatic modules.

**Considered solutions:**
1. Remove `Automatic-Module-Name` from the manifest
   - Fixes javadoc generation
   - Current module name already invalid for JPMS (contains dash, see #560)
   - Would not break working JPMS usage (already broken)
   - Removes future option to support JPMS once module name is fixed

2. Add `legacyMode=true` to `maven-javadoc-plugin`
   - Forces pre-Java 9 classpath-based javadoc generation instead of module mode
   - No changes to manifest (preserves invalid module name as-is)
   - Maven documentation recommends `legacyMode` when automatic module detection
     causes build issues
   - Used by other projects with automatic modules (e.g., Apache Avro PR 3041)

**Implementation:**
- Upgraded `maven-javadoc-plugin` from `3.5.0` to `3.11.2` (`legacyMode` added
  in `3.6.0`)
- Added `<legacyMode>true</legacyMode>` to force classpath-based generation

Both solutions were tested in separate git worktrees using Docker-based Maven
builds. Both produce identical javadoc output (`mcp-core`: 558 bytes → 1.4 MB,
474 HTML files). Solution 2 was chosen to avoid breaking changes.

Fixes javadoc generation for `mcp-core` and other modules using `bnd-maven-plugin`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 pom.xml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/pom.xml b/pom.xml
index ca9ce7be4..8f7ff4a7a 100644
--- a/pom.xml
+++ b/pom.xml
@@ -75,7 +75,7 @@
 		<maven-compiler-plugin.version>3.11.0</maven-compiler-plugin.version>
 		<maven-surefire-plugin.version>3.1.2</maven-surefire-plugin.version>
 		<maven-failsafe-plugin.version>3.5.2</maven-failsafe-plugin.version>
-		<maven-javadoc-plugin.version>3.5.0</maven-javadoc-plugin.version>
+		<maven-javadoc-plugin.version>3.11.2</maven-javadoc-plugin.version>
 		<maven-source-plugin.version>3.3.0</maven-source-plugin.version>
 		<jacoco-maven-plugin.version>0.8.10</jacoco-maven-plugin.version>
 		<flatten-maven-plugin.version>1.5.0</flatten-maven-plugin.version>
@@ -279,6 +279,7 @@
 						<version>${maven-javadoc-plugin.version}</version>
 						<configuration>
 							<detectJavaApiLink>false</detectJavaApiLink>
+							<legacyMode>true</legacyMode>
 							<failOnError>false</failOnError>
 							<doclint>none</doclint>
 							<additionalOptions>