Over a million developers have joined DZone.

Graphical Visualizations in JavaDoc

· Java Zone

The Java Zone is brought to you by Stormpath—offering a pre-built Identity API for developers. On 11/3 at 10AM PT, join Stormpath Developer Evangelist, Micah Silverman, to dive deep into using JWTs to protect microservices from CSRF and more. Register here!

Having code documentation is crucial for a software. It helps the developers to understand the functions and APIs. Code that is well understood is easier to improve, and therefore more likely to live on, instead of being thrown away in favor of a complete rewrite. It serves as the specification in case the code contradicts the text, and helps identifying possible bugs.

Sometimes explaining a situation only by words is difficult and results in lengthy, hard to comprehend blathering. What options for visualizations are there?

Option 1: Images

Although most Javadoc is plain text, it permits the use of HTML formatting. Images can be embedded. Put them into a doc-files folder and link it:

 * Visualization:
 * <p><img src="doc-files/my-uml-diagram.png"/></p>

There is some cost involved in keeping this up to date; the next programmer touching the code will need to have access to the originals, and have the graph software (UML, image editor, ...) installed. This takes time.

Also, chances are your IDE will not show the image. 

Javadoc history and today's use

When Javadoc was created in the early 90s, source code comments were nothing new. The pioneering feature was the auto-generation of a technical documentation directly from the source code. Prior to such documentation generators, the technical documentation used to be (badly) maintained separate from the source code. Ouch. HTML was brand new, and the build putting those files on a web server was cutting edge technology.

Now, Javadoc is over 20 years old. At the time it was created, virtually all business software was closed source. Today, all software libraries we are using at the company are open source.
Software projects reorganized from lengthy release cycles to release-early-release-often. And software is written in many smaller, modular pieces instead of monolithic systems.

Fact is, I rarely look at Javadoc in the web browser. Most often I see it directly in the IDE. Whether it's one of our own ~40 software projects, or a library checked out from GitHub or from Maven central, or code from the JDK itself. It's just so much better to have a complete view; up to date source code and Javadoc.

Option 2: ASCII Art

An alternative to images is the good old ascii art. I personally use and recommend asciidraw.

Here's an example:

 * <pre>
 *                 +---------gn-hypo-+                +--------------gn-+
 *                 |                 | +------------> |                 |
 *                 | Osquitar        |                | Óscar           |
 *                 |                 |       +------> |                 |
 *                 +-----------------+       |        +-----------------+
 *                                           |
 *                                           |
 *                                           |
 *                 +---------gn-hypo-+       |
 *                 |                 | +-----+
 *                 | Osqui           |                +--------------gn-+
 *                 |                 | +-------+      |                 |
 *                 +-----------------+         +----> | Osgar           |
 *                                                    |                 |
 *                                                    +-----------------+
 * </pre>

The advantages:
  1. It's quick, create a drawing within minutes.
  2. It's super simple, no special knowledge required.
  3. No "file originals" nor special software required.
  4. Every developer can maintain it.
  5. Any IDE or editor is guaranteed to display it in line.
  6. Because of the technical limitations, one is forced to keep it simple and focus on the main components.


You may want to consider ascii visualizations for your Javadoc the next time you're struggling with explaining a circumstance. It works great for us.

Article republished with permission from flowstopper http://www.flowstopper.org/2014/12/graphical-visualizations-in-javadoc.html

Building Identity Management, including authentication and authorization? Try Stormpath! Our REST API and robust Java SDK support can eliminate your security risk and can be implemented in minutes. Sign up, and never build auth again!


The best of DZone straight to your inbox.

Please provide a valid email address.

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}