User Assistance

As a Lua developer, you need a way to discover what the API of a given Lua module is. In your IDE, it means that you probably are interested in getting:

• autocompletion as you are typing code making use of the module,
• documentation when you are actually using the API of the module.

API Model

In LDT, we defined a model which expresses the API of a Lua module. See the specification of this model here.

The purpose of this model is to drive the autocompletion mechanism, as well as to allow HTML documentation generation. In order two build this model, there are two main alternatives:

• using static code analysis
• using a dedicated documentation language

The drawback of static code analysis is that there are many ways for a developer to implement a module, making it difficult to extract the API definition. We thought that it would not be realistic to try to support them all. Also, there would virtually be no way to generate the API model for modules written in C.

For a first version, it appeared to us that extracting information from a documentation language (like luadoc, ldoc) would surely be a better choice. This way, all module (libraries) providers could offer good user assistance with only a small effort on documentation. Plus, we are also capable of managing the "C modules" problem.

In a next version, it should be possible to use heuristics to extract API from common programming patterns.

Language Documentation

Ideally, this language should be a superset of LuaDoc. But as we said earlier, in our first version, all the information is extracted from the documentation language only. So it will not be available (at begin)

Typing is the main new concept, that will enable efficient autocompletion.

See definition of first version of this language. This is a little bit verbose but static code analysis will help later.

LuaDocumentor

A command line tool is necessary to allow user to generate HTML (or other format) documentation.

The luadocumentor.lua script can be used to generate either a website (a la Javadoc) or a set of Lua files containing solely the documentation of the APIs so as it can be given to end-users without exposing the associated source code.

Use lua luadocumentor.lua --help to learn more about the command line parameters.