BT

InfoQ Homepage News Compilation Meets Documentation

Compilation Meets Documentation

Bookmarks

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.

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

A significant amount of research has gone into API documentation and ways to catch errors or outdated calls. Researchers Seonah Lee, Rinxin Wu, Shing-Chi Chueng, and Sungwon Kang published similar research through the IEEE about the tool, FreshDoc, that analyzes and detects outdated API documentation. In a study analyzing the effectiveness of the documentation analysis, their paper states, "When we reported 40 outdated API names… developers accepted 70% of the suggestions."

The text of JEP-413 explains that the goal is to simplify the way that developers can create code documentation, but it will not stop all possible errors. For example, the JEP will not compile the code; rather developers should integrate their code snippets with CI/CD to validate code before extraction. This process keeps boilerplate, like import statements, out of the documentation but still readily available for anyone who wants to look.

If the JEP vote succeeds, the capabilities will be added to a future version of the Java documentation tools that help mark and create the documentation. A successful vote would have the most impact on API documentation tools such as JavaDoc and would not act as a replacement for the common trend of Getting Started Guides that introduce new programmers to what the API does and where to look in a project to find particular APIs.

We need your feedback

How might we improve InfoQ for you

Thank you for being an InfoQ reader.

Each year, we seek feedback from our readers to help us improve InfoQ. Would you mind spending 2 minutes to share your feedback in our short survey? Your feedback will directly help us continually evolve how we support you.

Take the Survey

Rate this Article

Adoption
Style

Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Community comments

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

BT

Is your profile up-to-date? Please take a moment to review and update.

Note: If updating/changing your email, a validation request will be sent

Company name:
Company role:
Company size:
Country/Zone:
State/Province/Region:
You will be sent an email to validate the new email address. This pop-up will close itself in a few moments.