| A good example of luadoc usage ... [message #1733313] |
Thu, 26 May 2016 08:34 |
Eclipse User |
|
|
|
Hello,
For those interested in a good example of a lua project with source code documented using luadoc, find my reference to the MOOSE Framework, that is currently in development for the DCS World community.
The MOOSE Framework is a lua framework for the simulator scripting engine, in order to make more complex mission scenarios using less code.
The code is completely documented using the LDT luadoc documentation standard and provides i guess an example on how to use the LDT luadoc coding standard.
You can view the project on GITHUB here:
https://github.com/FlightControl-Master/MOOSE
For an example on how the documentation looks like generated with luadocumentor, you can refer to the following web page:
http://flightcontrol-master.github.io/MOOSE/
I must say that building this documentation has a learning curve, because there are some quircks that you need to be aware off.
Some learning points:
1. A module name cannot be the same as your type names. If they are the same, the intellisense will not be able to make the difference and gets confused.
2. When you are in the middle of a function, and you want to make LDT aware of the type of certain variable, you can comment the variable declaration with a luadoc typing... See the following example:
--- @type CONTACT
-- @field #string Name
-- @field #string Address
-- @field #string City
do
local Contact -- #CONTACT
Contact.Name = "Sven"
Contact.Address = "Rubenslei"
Contact.City = "Antwerpen"
end
The intellisense will not know of what type Contact is, unless you "type" it using the luadoc standard.
3. The tool to generate the documentation set is luadocumentor. When you use luadocumentor currently using lua 5.2, it will generate an error. I had to recompile luadocumentor completely.
4. Make extensive use of the @param keyword and the @return keyword in your functions. They really help to get your code typed, and this is a really great feature! It requires some more work, but the benefits outweigh the effort.
5. Don't be lazy documenting your code. If you wait too long, you'll have a lot of work documenting all code. And this is really boring...
6. You can use the @{#type} references, but there are some issues with it. First, if you want to refer to a TYPE only, you'll have to write @{#TYPE} . But unfortunately, the ludocumentor tool will also show the # in the documentation. The second issue is with the functions. I use the ':' notation a lot as the MOOSE Framework is Object Oriënted. So, how to indicate in the lua documentation that the function is using the ':' notation? Only the '.' notation is available.
7. You MUST declare for a function written with the ':' notation a @param entry indicating the #TYPE self. Otherwise it will not understand what type self is of your function (which is a bit silly, because the function is declared under the #TYPE) ... Find below an example:
--- @type CONTACT
-- @field #string Name
-- @field #string Address
-- @field #string City
CONTACT = {}
--- Set the Name
-- @param Name
function CONTACT:SetName( Name )
self.Name = Name
end
do
CONTACT:SetName( "Sven" )
end
The intellisense will not understand the self variable in the function, so self.Name will not intellisense...
However, if you add @param #CONTACT self, then it will work.
--- Set the Name
-- @param Name
function CONTACT:SetName( Name )
self.Name = Name
end
Hope this is helpful for some,
Sven
[Updated on: Thu, 26 May 2016 01:32] by Moderator |
|
|
Powered by
FUDForum. Page generated in 0.03060 seconds
Home