LDT/Developer Area/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.
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.
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.
A command line tool is necessary to allow user to generate HTML (or other format) documentation.
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.
lua luadocumentor.lua --help to learn more about the command line parameters.
A prototype of the Lua Development Tools standalone distribution including the brand new user assistance, as well as SDK definitions of Lua 5.1, Corona (incomplete), LÖVE2D (incomplete) and VLC (incomplete), and the command-line documentation generator have been made available here
In order to reference an SDK in your Lua project, you need to right-click on the project, select "Build Path > Add External Archives...", and then add you SDK of choice. It will then enhance your project path with the globals declared inside this archive.
Important note: the code of this prototype is technically under open source licenses (EPL and MIT), but is currently under IP review at Eclipse. We wanted to make it available earlier so as the community at large can give feedback.