> 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.
I'll look at LuaDoc, but I don't think it addresses what I need. The
issue is that metadata about the protocol (for example, what products
implement a message, if a message is read only, relationships between
messages for sequencing) would be a comment, not something that could
be used at run-time. If it wasn't clear, the documentation I'm
talking about isn't code documentation, since end users don't have
access to the code. Users interact with the device by sending
messages, and the documentation provides the protocol for those
messages.
I wasn't intending that end users would read the comments in the code. With any of those tools, you generate html, which then documents what the code does. For example, take a look at the Java API - You may never look at the source of those classes, because the HTML is generally sufficient. However, I'm an embedded systems developer as well, and there are frequently times that I need to go to the source because it's not working like it should. I would be wary of working with a device that implemented a protocol for which I don't have the source code.
> 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.
The generation of code from the protocol description isn't driven by a
fear of the efficiency of Lua. It's driven by the fact that I don't
think Lua is going to be running on a 8-bit Freescale HCS08
microcontroller running at 24MHz anytime soon. And the larger
platform the C code targets is a ColdFire that has about 16k of RAM
left over and about twice that in ROM. Yes, I'm one of those embedded
systems guys who hangs out in this mailing list to remind everyone
that while Lua can go lots of places, it can't go everywhere.
Those are a little small for embedded Lua, but I think the ColdFire is well within the realm of possibility. But, you're right, native code is still your best bet for those two. I'm an embedded systems guy as well, and I've used eLua previously. I assume you've read
this thread about eLua on a ColdFire?
