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
