title: What is a popular JavaDoc practice for ASCII-art documentation?
body: <p>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.</p>
  
  <p>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.</p>
  
  <p>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: </p>
  
  <ol>
  <li>Embed an image.</li>
  <li>Use an HTML table.</li>
  </ol>
  
  <p>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.</p>
  
  <p>The HTML table option is bad for two reasons. First, the Eclipse formatter puts <em>each tag and value on it's own line</em>, 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.</p>
  
  <p>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.</p>
  
  <hr>
  
  <p><strong>Edit</strong>: I just found <a href="https://code.google.com/p/markdown-doclet/" rel="noreferrer">markdown-doclet</a>. I don't know if this will be an acceptable compromise or not. Maybe there are other tools that work similarly?</p>