Re: Describing a native SDK in a sane manner.

[steve donovan <steve.j.donovan@...>]

On Tue, Aug 13, 2013 at 2:18 AM, Jon Akhtar <akhtar@mindspring.com> wrote:

The problem with this of course is it is quite complicated by nature, and to top it off my system used the module function as a sort of pseudo keyword in order to reduce the overally complexity of code analysis. For example getting all the Penlight code to understand its own self references took some work - but it did work last time I tried browsing the source.

My apologies ;)  require 'pl' does nasty things to the Lua state, which is why it's only recommended for quick-and-dirty scripts. However convenience always overcomes warnings.

I know that the Koneki project (doing the 'official' Lua plugin for Eclipse) have hit exactly these issues. Fabien and co pushed for typed tag annotations in LDoc, including return values, to help the static analysis.  Hence @tparam int and its short form @int, and so forth.

They then went off and defined their own way of doing things:

http://wiki.eclipse.org/Koneki/LDT/Technical_Documentation/Documentation_Language

What I consider a fail in their implementation, is that they don't infer things like function names. Most of the LuaDoc-ified modules out there assume that the processor is smart enough to work that out ;)  So - you have to instrument code specifically for that Lua development system.

steve d.