What is a popular JavaDoc practice for ASCII-art documentation? [closed]

Question

I'm working on a project written in Java, designed to transmit data via a messaging system that strictly defines the bit position of the messages fields. This means we have an entire library of dictionary classes designed to bit-shift object input data to/from the message binary representation. This library is reasonably large, and because the protocol is still young, has the tendency to be tweaked and changed every year or so.

The JavaDoc for this library provides ASCII art tables and diagrams that explain what a particular method expects as input (or output). These tables are exceedingly important because finding the documentation and verifying that the method actually does what the document says can be time consuming a prone to error. Following a single, simple ASCII-representation of the bit shifting makes this a lot easier.

I have a coworker who insists that ASCII art does not belong in JavaDoc (even with tags), and furthermore that we configure Eclipse to automatically format the code on save. He offers two options to reformat the documentation:

1. Embed an image.
2. Use an HTML table.

The image would be okay, except Eclipse doesn't render SVG images. It is completely unacceptable to me that we maintain an SVG image and then export the image as PNG to our documentation repo, and then link the PNG with HTML. The amount of maintenance involved in that scenario seems completely crazy. Who is responsible for making sure all the PNG, SVG, and code are synchronized?? Furthermore, obviously, the data won't be readable without the image.

The HTML table option is bad for two reasons. First, the Eclipse formatter puts each tag and value on it's own line, which means every single value takes up three lines. It leaves huge gaps in the source code, and is completely unreadable without rendering the HTML. To make matters worse, some of our tables are complex, and troubleshooting HTML tables is not my idea of a responsible thing to require of developers who already resist creating documentation.

So if my coworker is right about "java people" not using ASCII diagrams for documentation, what is a standard, industry practice, that gives us a method for preserving these diagrams? How does this method benefit over using tags with ASCII diagrams? Bonus points if you can answer why JavaDoc hasn't evolved to provide readable markup, instead of relying on HTML.

---

Edit: I just found markdown-doclet. I don't know if this will be an acceptable compromise or not. Maybe there are other tools that work similarly?

Answer 1

An old question, but I have had similar frustrations.

• You can use the /*- construct to prevent Eclipse from formatting a given comment. See: https://stackoverflow.com/a/5466173.

• Use the {@code} construct and/or <pre>. See: https://stackoverflow.com/a/542142. I suppose someone who argues against ASCII diagrams in general would argue against these, too. But perhaps it's having been enshrined in Javadoc syntax will be a point in your favor.

• Point out that even the Java developers use ASCII diagrams where appropriate.

• You could also tell your fellow to use a better editor. No, no, I troll (: ...A little.

Answer 2

At the company we've decided on ASCII diagrams for the primary reasons given already, and we believe they are more than enough to justify this choice:

1. Maintenance cost and feasibility.
   I've seen projects with outdated external resources... it's almost inevitable.
2. Displayed anywhere (IDE, text editor).
   We don't produce Javadoc for internal projects and put them on a web server. Development habits have changed... see http://www.flowstopper.org/2014/12/graphical-visualizations-in-javadoc.html

ASCII diagrams also force one to keep it simple, which usually helps for clarity.

I've found http://www.asciidraw.com/ to be a great tool for this purpose.