Skip to main content


Eclipse Community Forums
Forum Search:

Search      Help    Register    Login    Home
Home » Eclipse Projects » Lua Development Tools » A good example of luadoc usage ...(For those interested in how to use luadoc in your lua code using LDT)
A good example of luadoc usage ... [message #1733313] Thu, 26 May 2016 12:34
Sven Van de Velde is currently offline Sven Van de VeldeFriend
Messages: 15
Registered: March 2016
Junior Member
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 05:32]

Report message to a moderator

Previous Topic:for id, element in pairs( table ) do -- How to use luadoc?
Next Topic:Crash when upgrading to new debugger.lua
Goto Forum:
  


Current Time: Tue Sep 25 19:19:04 GMT 2018

Powered by FUDForum. Page generated in 0.08434 seconds
.:: Contact :: Home ::.

Powered by: FUDforum 3.0.2.
Copyright ©2001-2010 FUDforum Bulletin Board Software

Back to the top