Compilation meets documentation: OpenJDK JEP-413

The OpenJDK community has proposed JEP-413 as a way to add compilable source code snippets to the 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 used in major projects such as the Azure SDK, R language, NetBeans, and GraalVM. Developers working on custom projects with documentation can take advantage of an existing project by NetBeans architect Jaroslav Tulach, CodeSnippet4Javadoc.

GraalVM project manager Thomas Wuerthinger said“This is a great initiative! We are currently using a custom developed solution to create snippets in our GraalVM documentation…”

The conversation identified a commonality in large development projects to discuss how many projects have arrived at a similar solution to view and monitor errors in their documentation. “We do the same in Azure SDK,” remarked Jonathan Giles, Principal Java Architect for Microsoft working on the Azure SDK. “I can’t wait to spend some time on this if it works as a suitable replacement.” JEP stands for Java Enhancement Proposal, which means that a vote on the proposal and follow-on integration is required for the project to pass into the Java ecosystem.

The benefit of compilable source code snippets can impact developers who read the documentation and then use the sample code provided in their own projects. The tendency of developers to copy + paste code is well known in the industry, where StackOverflow has released a parody keyboard for April Fools 2021 with three keys: ctrl, c and v. The joke parodies copy/paste keyboard shortcuts and opens with the tagline: “Good artists copy. Great artists steal. Great artists copy, then paste.”

A significant amount of research has gone into API documentation and ways to catch errors or stale calls. Researchers Seonah Lee, Rinxin Wu, Shing-Chi Chueng, and Sungwon Kang published similar research via IEEE on the FreshDoc tool, which scans and detects outdated API documentation. In a study analyzing the effectiveness of documentation scanning, their article states, “When we reported 40 deprecated API names…developers accepted 70% of suggestions.”

The JEP-413 text explains that the goal is to simplify the way developers can create code documentation, but that won’t prevent all possible errors. For example, the JEP will not compile code; instead, developers should integrate their code snippets with CI/CD to validate the code before the checkout. This process keeps boilerplate, like import instructions, out of the documentation, but still readily available for anyone to view.

If the JEP vote is successful, the features will be added to a future release of the Java Documentation Tools that help mark up and create documentation. A successful vote would have the most impact on API documentation tools such as JavaDoc and would not replace the common trend of getting started guides that introduce new programmers to what the API does and where to look in a project for find particular APIs. .

Sam D. Gomez