Re: Protocol Specification in Lua

[John Passaniti <john@...>]

On Fri, Oct 1, 2010 at 1:53 PM, Kevin Vermeer <reemrevnivek@gmail.com> wrote:
> 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.

> 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.

Beyond those hardware targets, the command-line tools I described that
disassemble and construct messages and write out user documentation
will be written in Lua, and I have no problem using pure Lua code
there.  Lua is plenty fast for that.