On Fri, Oct 1, 2010 at 12:30 PM, John Passaniti
<john@japanisshinto.com> wrote:
I'm looking for a little design inspiration from others. I have a
basic approach (which I'll describe, below), but chances are good that
someone here has already implemented something like this or can see a
better solution.
I have a UDP-based communications protocol for controlling a device.
The protocol is implemented in C and specified in a tedious Microsoft
Word document. The base protocol is simple and extensible and isn't
interesting. What is interesting is there are a large number of
binary messages, each with a unique structure. I'm bothered that when
I change the C code to add a new message, I also have to update the
Word document. The two are separate things.
I'd like to write a tool that could parse these messages and display
them in human readable form. And I'd like another tool that does the
reverse-- specify a message in a human-readable form, and get back out
a message. And I'd like to be able to write a Wireshark dissector for
these messages. And I'd like... well, more stuff.
The solution would seem to be to express the protocol in some
abstract, high-level representation (like... a Lua table). Once in
this form, I can write a tool that will dump out a description of the
protocol in HTML. I could also have it generate optimized C code to
implement the protocol parser (such as converting to a finite state
machine). The table would also be at the heart of the Wireshark
dissector and the tools to display and create packets. And so on.
This is an interesting idea, and I look forward to seeing where it goes. However, assuming that your code isn't self-documenting in its clarity (and C is rarely self-documenting), you should have not two but three places to update when you make a change: The code, the documentation, and *comments* in the code.
These three sources have historically be reduced to two by using a tool to go from the comments to the documentation.
Doxygen is useful for a host of languages, and you might also be familiar with
LuaDoc or JavaDoc. Unless you have a *lot* of documentation to do, I think the best path would be to define the binary messages in Lua, and document there with LuaDoc. Then, you could generate your HTML documentation from these source files ( source = code + comments). If you'd prefer to continue adding the messages as C source out of personal preference, the ease of updating comments as opposed to creating an interface/tool, or due to concerns about the efficiency of Lua (you mention "optimized C", though it may be a little early to worry about that), then you could use Doxygen.
Both of these methods reduce the number of files to edit to a single source file, but sustain a requirement to make the edits in two places. Inconsistency between comments and the code they describe is the root of a lot of problems. Traditionally, religiously keeping the two consistent and generating documents from the comments is enough. However, this solution sounds interesting! I look forward to following the rest of this thread.
--
Kevin Vermeer
