I am working on a project written in Java designed to transmit data through a messaging system that strictly determines the position of the bits of message fields. This means that we have a whole library of dictionary classes designed to enter data with a binary change of the object to / from the binary representation of the message. This library is large enough because the protocol is still young, tends to change and change 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 extremely important because finding documentation and verifying that the method actually does what the document says can be time consuming, exposing errors. After a simple simple ASCII representation of the bit offset, this is much simpler.
I have an employee who insists that ASCII art does not belong to JavaDoc (even with tags), and in addition, we configure Eclipse to automatically format the code when saving. He offers two options for reformatting the documentation:
- Insert image.
- Use an HTML table.
The image will be fine except that Eclipse does not display SVG images. It is completely unacceptable to me that we save the SVG image and then export the image as PNG to our repo documentation, and then link the PNG to HTML. The scope of maintenance associated with this scenario seems completely crazy. Who is responsible for ensuring that all PNG, SVG and code are in sync? In addition, it is obvious that the data will not be readable without an image.
HTML- . -, Eclipse , , . HTML. , , HTML- - , , .
, "java people", ASCII , , ? ASCII? , , JavaDoc , , HTML.
. markdown-doclet. , . , , ?