Compilation Meets Documentation: OpenJDK JEP-413

submited by

Style Pass

2021-05-26 21:30:04

InfoQ Homepage News Compilation Meets Documentation: OpenJDK JEP-413

The OpenJDK community has proposed JEP-413 as a way to add compilable source snippets to API documentation. This approach will simplify the role of maintainers who work on their examples as well as readers who want to copy working code.

The approach of compiling code as documentation snippets is already in use within major projects like the Azure SDK, the R language, NetBeans, and GraalVM. Developers working on custom projects with documentation can leverage an existing project by NetBeans architect Jaroslav Tulach, CodeSnippet4Javadoc.

GraalVM project lead Thomas Wuerthinger declared, "This is a great initiative! We are currently using a custom developed solution to make snippets in our GraalVM documentation..."

The conversation identified a commonality in large developer projects to discuss the way that many projects arrived on a similar solution to show and monitor for errors in their documentation. "We do the same in Azure SDK," remarked Jonathan Giles, Principal Java Architect for Microsoft who works on the Azure SDK. "I look forward to one day moving to this if it works out as an appropriate replacement." JEP stands for Java Enhancement Proposal, meaning a vote on the proposal and follow-on integration is needed for the project to move into the Java ecosystem.