The Illuminating Javadoc of JDK 8

One of the nice features of the standard JDK 8 API documentation is the ability to view all or different categories of methods as discussed in my blog post JDK 8 Javadoc Tweaked For Methods Listings. As convenient and useful as this categorization is, the text comments associated with many of the new classes and packages in JDK 8 are arguably even more useful, especially as many of us start to adopt JDK 8. I look at some of examples of highly useful JDK 8 API documentation in this post. In the course of this quick perusal of the JDK 8 Javadoc documentation, anyone entirely new to JDK 8 is bound to learn something about the libraries of JDK 8.

Good examples of the usefulness of the JDK 8 API documentation are in the familiar String class documentation. That class features two new overloaded static methods, join(CharSequence, CharSequence…) and join(CharSequence delimiter, Iterable elements). The Javadoc comments for these two new methods not only explain the methods’ behaviors, but illustrate them with code that demonstrates the methods in use. This is similar to the Javadoc comment I’ve always found helpful on the String.substring(int, int) method.

The all-new StringJoiner class includes code examples of its usage in the class-level Javadoc comments. One of the code examples seems targeted toward easing “traditional Java development” while the second example applies the power of lambda expressions and streams.

Code examples are used liberally in other new (to JDK 8) classes’ Javadoc documentation as well, especially in the java.util.streams package. The class-level Javadoc documentation for the java.util.stream.Collectors class provides code examples of 7 potential uses for Collectors such as accumulation and grouping. The Stream interface provides an example of useful JDK 8 documentation on an interface. The text detail on applying the Stream interface is accompanied by a simple code example that demonstrates “an aggregate operation using Stream and IntStream.” The java.util.stream package itself has great description text regarding Streams that includes a simple example of employing a Stream with a detailed discussion of what is going on with that example. The package documentation for java.util.stream goes onto discuss several different aspects of using Streams such as stream operations and pipelines, parallelism, side effects, and reduction.

Just as it is important to understand Streams when working with JDK 8 lambda expressions, it is also useful to understand functional interfaces when using lambda expressions and the java.util.function package-level description provides a nice overview.

Another good example of JDK 8 Javadoc-based documentation with enlightening code examples is the documentation for Calendar.Builder, a class I covered in the post JDK 8′s Calendar.Builder.

Most of the JDK 8 Javadoc-based documentation I’ve discussed so far provides code examples demonstrating use of the described package, class, or interface. Some of the new JDK API documentation uses code to demonstrate the new API feature by showing code that formerly would have needed to be written but is replaced by the new feature. Good examples of this exist in the well-known Java Map interface. The Java Map interface has several new methods specified in JDK 8 and many of these new JDK 8 methods include Javadoc documentation indicating code that would have been required prior to JDK 8 to accomplish the same thing as the newly added method. For example, the methods computeIfAbsent, computeIfPresent, forEach, getOrDefault, and putIfAbsent methods all have comments providing code demonstrating what the “default implementation is equivalent to.” Although this may be explaining the default behavior of Map implementations, it is also useful for understanding the type of pre-JDK 8 code these methods emulate or replace.

JDK 8 introduces a completely new Date/Time API and the java.time package has a nice package-level overview of the API. Constructs in this entirely new package have individual level comments that are useful for learning this API. Examples include Clock, Instant, LocalDateTime, Period, and ZonedDateTime. The package-level documentation helps clarify the relationship between LocalDate, LocalDateTime, LocalTime, ZonedDateTime, and Instant.

JDK 8 Javadoc isn’t only changed for the standard JDK API. JDK 8 brings some enhancements to the javadoc tool that will impact developers’ own Javadoc comments and code. It is also important to be aware of the -Xdoclint:none option (mentioned in Stephen Colebourne’s blog post Turning off doclint in JDK 8 Javadoc) for preventing Javadoc that doesn’t conform to “W3C HTML 4.01 HTML” from breaking. The final bullet on the Enhancements in Javadoc, Java SE 8 page states that this Javadoc HTML conformance compliance “feature is also available in javac, although it is not enabled by default there.” That same bullet tells us that we can learn more about the -Xdoclint:none flag by running javadoc -X.

Conclusion

I sometimes hear that there is never a need for comments when the code speaks for itself. I believe that is true to a degree, but the presence of useful Javadoc comments on packages, classes, and interfaces and their methods that were introduced with JDK 8 will make the adoption of JDK 8 much quicker than reading everyone of these constructs’ code listings would. It reinforces my opinion that we often don’t need comments on specific lines of code that do something, but most often do need comments on interfaces and contracts. In my ideal world, the code would be so well written that the only necessary comments would be Javadoc style comments (/** */) and we’d need very little // or /* */ style comments. JDK 8 continues a trend that has occurred in recent major revisions of the JDK of improved Javadoc comments in terms of readability and understandability.

Related Whitepaper:

Bulletproof Java Code: A Practical Strategy for Developing Functional, Reliable, and Secure Java Code

Use Java? If you do, you know that Java software can be used to drive application logic of Web services or Web applications. Perhaps you use it for desktop applications? Or, embedded devices? Whatever your use of Java code, functional errors are the enemy!

To combat this enemy, your team might already perform functional testing. Even so, you're taking significant risks if you have not yet implemented a comprehensive team-wide quality management strategy. Such a strategy alleviates reliability, security, and performance problems to ensure that your code is free of functionality errors.Read this article to learn about this simple four-step strategy that is proven to make Java code more reliable, more secure, and easier to maintain.

Get it Now!  

Leave a Reply


− 1 = eight



Java Code Geeks and all content copyright © 2010-2014, Exelixis Media Ltd | Terms of Use | Privacy Policy
All trademarks and registered trademarks appearing on Java Code Geeks are the property of their respective owners.
Java is a trademark or registered trademark of Oracle Corporation in the United States and other countries.
Java Code Geeks is not connected to Oracle Corporation and is not sponsored by Oracle Corporation.

Sign up for our Newsletter

20,709 insiders are already enjoying weekly updates and complimentary whitepapers! Join them now to gain exclusive access to the latest news in the Java world, as well as insights about Android, Scala, Groovy and other related technologies.

As an extra bonus, by joining you will get our brand new e-books, published by Java Code Geeks and their JCG partners for your reading pleasure! Enter your info and stay on top of things,

  • Fresh trends
  • Cases and examples
  • Research and insights
  • Two complimentary e-books