Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "LDT/Developer Area/User Assistance"
(New page: = User Assistance = We need a way to help users to discover Lua module API. The key features to achieve this goal are : * module autocompletion * module documentation ==API Model== We def...) |
m |
||
| Line 1: | Line 1: | ||
= User Assistance = | = 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== | ==API Model== | ||
| − | |||
| − | + | In LDT, we defined a model which expresses the API of a Lua module. See the specification of this model [[Koneki/LDT/Technical_Discussions/Lua_API_Model_2|here]]. | |
| − | The | + | 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: | |
| − | * static code analysis | + | * using static code analysis |
| − | * documentation language | + | * using a dedicated documentation language |
| − | The | + | 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, | + | 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 | + | In a next version, it should be possible to use heuristics to extract API from common programming patterns. |
==Language Documentation== | ==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 [[Koneki/LDT/Technical_Discussions/Documentation_Language | definition of first version of this language]]. This is a little bit verbose but static code analysis will help later. | See [[Koneki/LDT/Technical_Discussions/Documentation_Language | definition of first version of this language]]. This is a little bit verbose but static code analysis will help later. | ||
Revision as of 15:32, 10 February 2012
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 tools is necessary to allow user to generate html (or other format) documentation.
Prototype
We will deliver a prototype soon.