Skip to content

Commit 1a928f2

Browse files
fix: Enable javadoc generation for modules with OSGi metadata
**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 modelcontextprotocol#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 - Added `<detectModules>false</detectModules>` and explicit `<outputDirectory>` 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`.
1 parent e6045f7 commit 1a928f2

1 file changed

Lines changed: 4 additions & 1 deletion

File tree

‎pom.xml‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@
7575
<maven-compiler-plugin.version>3.11.0</maven-compiler-plugin.version>
7676
<maven-surefire-plugin.version>3.1.2</maven-surefire-plugin.version>
7777
<maven-failsafe-plugin.version>3.5.2</maven-failsafe-plugin.version>
78-
<maven-javadoc-plugin.version>3.5.0</maven-javadoc-plugin.version>
78+
<maven-javadoc-plugin.version>3.11.2</maven-javadoc-plugin.version>
7979
<maven-source-plugin.version>3.3.0</maven-source-plugin.version>
8080
<jacoco-maven-plugin.version>0.8.10</jacoco-maven-plugin.version>
8181
<flatten-maven-plugin.version>1.5.0</flatten-maven-plugin.version>
@@ -279,13 +279,16 @@
279279
<version>${maven-javadoc-plugin.version}</version>
280280
<configuration>
281281
<detectJavaApiLink>false</detectJavaApiLink>
282+
<detectModules>false</detectModules>
283+
<legacyMode>true</legacyMode>
282284
<failOnError>false</failOnError>
283285
<doclint>none</doclint>
284286
<additionalOptions>
285287
<additionalOption>-Xdoclint:none</additionalOption>
286288
</additionalOptions>
287289
<source>${java.version}</source>
288290
<quiet>true</quiet>
291+
<outputDirectory>${project.build.directory}/apidocs</outputDirectory>
289292
</configuration>
290293
<executions>
291294
<execution>

0 commit comments

Comments
 (0)