97 Things Every Java Programmer Should Know

Chapter 3. Augment Javadoc with AsciiDoc

James Elliott

Java developers already know Javadoc. Those who’ve been around a long time remember how transformative it was, as Java became the first mainstream language to integrate a documentation generator right into the compiler and standard toolchain. The resulting explosion of API documentation (even if not always great or polished) has hugely benefited us all, and the trend has spread to many other languages. As James Gosling reported, Javadoc was initially controversial because “a good tech writer could do a lot better job”—but there are vastly more APIs than tech writers to document them, and the value of having something universally available has been well established.

Sometimes you need more than API documentation, though—much more than you can fit in the package and project overview pages Javadoc offers. End-user-focused guides and walk-throughs, detailed background on architecture and theory, explanations of how to fit together multiple components…none of these fit comfortably within Javadoc.

So what can we use to meet these other needs? The answers have changed over time. FrameMaker was a groundbreaking cross-platform GUI technical document powerhouse in the ʼ80s. Javadoc even used to include a MIF Doclet for generating attractive printed API documentation with FrameMaker—but only a vestigial Windows version remains. DocBook ...