Skip to content

Commit d5a2968

Browse files
jonathanhefnerclaude
jonathanhefner
and
claude
committed
Enable markdown documentation in javadoc using JDK 23 toolchain
Add support for markdown documentation files (`overview.md`, `doc-files/`) by configuring a JDK 23 toolchain for javadoc generation while keeping JDK 17 as the build target. - Add javadoc-toolchain profile that uses JDK 23 for markdown rendering - Update CI workflows to set up both JDK 17 and JDK 23 - Add markdown `overview.md` as the javadoc landing page - Add documentation for contributors on adding javadoc content 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent fa9dac8 commit d5a2968

File tree

7 files changed

+146
-13
lines changed

7 files changed

+146
-13
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ name: CI
22

33
on:
44
pull_request: {}
5+
workflow_dispatch: {}
56

67
jobs:
78
build:
@@ -11,12 +12,25 @@ jobs:
1112
- name: Checkout source code
1213
uses: actions/checkout@v4
1314

15+
- name: Set up JDK 23 for Javadoc toolchain
16+
uses: actions/setup-java@v4
17+
with:
18+
java-version: '23'
19+
distribution: 'temurin'
20+
1421
- name: Set up JDK 17
1522
uses: actions/setup-java@v4
1623
with:
1724
java-version: '17'
1825
distribution: 'temurin'
1926
cache: 'maven'
2027

21-
- name: Build
28+
- name: Build and test
29+
env:
30+
JAVA_HOME: ${{ env.JAVA_HOME_17_X64 }}
2231
run: mvn verify
32+
33+
- name: Validate Javadoc generation
34+
env:
35+
JAVA_HOME: ${{ env.JAVA_HOME_17_X64 }}
36+
run: mvn -Pjavadoc,javadoc-toolchain javadoc:aggregate

‎.github/workflows/maven-central-release.yml‎

Lines changed: 17 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,14 @@ jobs:
88
runs-on: ubuntu-latest
99
steps:
1010
- uses: actions/checkout@v4
11-
12-
- name: Set up Java
11+
12+
- name: Set up JDK 23 for Javadoc toolchain
13+
uses: actions/setup-java@v4
14+
with:
15+
java-version: '23'
16+
distribution: 'temurin'
17+
18+
- name: Set up JDK 17
1319
uses: actions/setup-java@v4
1420
with:
1521
java-version: '17'
@@ -25,17 +31,20 @@ jobs:
2531
uses: actions/setup-node@v4
2632
with:
2733
node-version: '20'
28-
34+
2935
- name: Build and Test
36+
env:
37+
JAVA_HOME: ${{ env.JAVA_HOME_17_X64 }}
3038
run: mvn clean verify
3139

3240
- name: Publish to Maven Central
33-
run: |
34-
mvn --batch-mode \
35-
-Prelease \
36-
-Pjavadoc \
37-
deploy
3841
env:
3942
MAVEN_USERNAME: ${{ secrets.OSSRH_USERNAME }}
4043
MAVEN_PASSWORD: ${{ secrets.OSSRH_TOKEN }}
4144
MAVEN_GPG_PASSPHRASE: ${{ secrets.SIGNING_PASSPHRASE }}
45+
JAVA_HOME: ${{ env.JAVA_HOME_17_X64 }}
46+
run: |
47+
mvn --batch-mode \
48+
-Prelease \
49+
-Pjavadoc,javadoc-toolchain \
50+
deploy

‎.github/workflows/publish-snapshot.yml‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,12 @@ jobs:
1212
- name: Checkout source code
1313
uses: actions/checkout@v4
1414

15+
- name: Set up JDK 23 for Javadoc toolchain
16+
uses: actions/setup-java@v4
17+
with:
18+
java-version: '23'
19+
distribution: 'temurin'
20+
1521
- name: Set up JDK 17
1622
uses: actions/setup-java@v4
1723
with:
@@ -29,16 +35,14 @@ jobs:
2935
with:
3036
node-version: '20'
3137

32-
- name: Generate Java docs
33-
run: mvn -Pjavadoc -B javadoc:aggregate
34-
3538
- name: Build with Maven and deploy to Sonatype snapshot repository
3639
env:
3740
MAVEN_USERNAME: ${{ secrets.OSSRH_USERNAME }}
3841
MAVEN_PASSWORD: ${{ secrets.OSSRH_TOKEN }}
3942
MAVEN_GPG_PASSPHRASE: ${{ secrets.SIGNING_PASSPHRASE }}
43+
JAVA_HOME: ${{ env.JAVA_HOME_17_X64 }}
4044
run: |
41-
mvn -Pjavadoc -Prelease --batch-mode --update-snapshots deploy
45+
mvn -Pjavadoc,javadoc-toolchain -Prelease --batch-mode --update-snapshots deploy
4246
4347
- name: Capture project version
4448
run: echo PROJECT_VERSION=$(mvn help:evaluate -Dexpression=project.version --quiet -DforceStdout) >> $GITHUB_ENV

‎mcp-core/src/main/javadoc/io/modelcontextprotocol/doc-files/.gitkeep‎

Whitespace-only changes.

‎pom.xml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@
7676
<maven-surefire-plugin.version>3.1.2</maven-surefire-plugin.version>
7777
<maven-failsafe-plugin.version>3.5.2</maven-failsafe-plugin.version>
7878
<maven-javadoc-plugin.version>3.11.2</maven-javadoc-plugin.version>
79+
<javadoc.jdk.version>23</javadoc.jdk.version>
7980
<maven-source-plugin.version>3.3.0</maven-source-plugin.version>
8081
<jacoco-maven-plugin.version>0.8.10</jacoco-maven-plugin.version>
8182
<flatten-maven-plugin.version>1.5.0</flatten-maven-plugin.version>
@@ -266,6 +267,7 @@
266267
</build>
267268

268269
<profiles>
270+
<!-- Base javadoc profile - uses current JDK -->
269271
<profile>
270272
<id>javadoc</id>
271273
<activation>
@@ -287,6 +289,9 @@
287289
</additionalOptions>
288290
<source>${java.version}</source>
289291
<quiet>true</quiet>
292+
<docfilessubdirs>true</docfilessubdirs>
293+
<javadocDirectory>${project.basedir}/src/main/javadoc</javadocDirectory>
294+
<overview>${project.basedir}/src/main/javadoc/overview.md</overview>
290295
</configuration>
291296
<executions>
292297
<execution>
@@ -308,6 +313,26 @@
308313
</plugins>
309314
</build>
310315
</profile>
316+
<!-- CI profile - requires JDK 23 toolchain for markdown support -->
317+
<profile>
318+
<id>javadoc-toolchain</id>
319+
<activation>
320+
<activeByDefault>false</activeByDefault>
321+
</activation>
322+
<build>
323+
<plugins>
324+
<plugin>
325+
<groupId>org.apache.maven.plugins</groupId>
326+
<artifactId>maven-javadoc-plugin</artifactId>
327+
<configuration>
328+
<jdkToolchain>
329+
<version>${javadoc.jdk.version}</version>
330+
</jdkToolchain>
331+
</configuration>
332+
</plugin>
333+
</plugins>
334+
</build>
335+
</profile>
311336
<profile>
312337
<id>release</id>
313338
<build>

‎src/main/javadoc/README.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Javadoc Documentation
2+
3+
This directory contains documentation that is included in the generated Javadoc.
4+
5+
## Adding Documentation
6+
7+
### Overview Page
8+
9+
Edit `overview.md` in this directory for the main project overview page.
10+
11+
### Additional Pages
12+
13+
Place markdown files in `mcp-core/src/main/javadoc/io/modelcontextprotocol/doc-files/`.
14+
15+
Example: `mcp-core/src/main/javadoc/io/modelcontextprotocol/doc-files/getting-started.md`
16+
17+
## Requirements
18+
19+
- **JDK 23+** is required to generate javadocs with markdown support (JEP 467)
20+
- Files use CommonMark syntax with GitHub-flavored tables
21+
- Generate docs locally: `mvn -Pjavadoc javadoc:aggregate`
22+
23+
## Linking to Documentation
24+
25+
From javadoc comments, link to doc-files:
26+
27+
```java
28+
/**
29+
* See the <a href="doc-files/getting-started.html">Getting Started guide</a>.
30+
*/
31+
```
32+
33+
Note: Link to `.html` even though source is `.md` - the javadoc tool converts them.
34+
35+
From the overview page, use relative links:
36+
37+
```markdown
38+
See [Getting Started](io/modelcontextprotocol/doc-files/getting-started.html)
39+
```
40+
41+
## Markdown Syntax
42+
43+
The javadoc tool supports CommonMark with these extensions:
44+
45+
- GitHub-flavored tables
46+
- Fenced code blocks with syntax highlighting
47+
- Links to Java elements: `[text][java.util.List]`
48+
49+
For full details, see [JEP 467: Markdown Documentation Comments](https://openjdk.org/jeps/467).

‎src/main/javadoc/overview.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# MCP Java SDK
2+
3+
Java SDK for the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP), enabling Java applications to interact with AI models and tools through a standardized interface.
4+
5+
The source code is available at [github.com/modelcontextprotocol/java-sdk](https://github.com/modelcontextprotocol/java-sdk).
6+
7+
## Modules
8+
9+
- **mcp** - Convenience module that bundles core dependencies
10+
- **mcp-core** - Core reference implementation
11+
- **mcp-json** - JSON abstraction layer
12+
- **mcp-json-jackson2** - Jackson JSON implementation
13+
- **mcp-spring-webflux** - Spring WebFlux transport
14+
- **mcp-spring-webmvc** - Spring WebMVC transport
15+
16+
## Getting Started
17+
18+
Add the MCP SDK to your project:
19+
20+
```xml
21+
<dependency>
22+
<groupId>io.modelcontextprotocol.sdk</groupId>
23+
<artifactId>mcp</artifactId>
24+
<version>${mcp.version}</version>
25+
</dependency>
26+
```
27+
28+
## Additional Documentation
29+
30+
- [MCP documentation](https://modelcontextprotocol.io)
31+
- [MCP specification](https://modelcontextprotocol.io/specification/latest)
32+
- [Spring AI MCP Documentation](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-overview.html)

0 commit comments

Comments
 (0)