Hi,
Thanks for your feedback !
1) For the ‘#’
We decided to have a way to visualize easily and quickly the difference between a type name and something else (and technically it also helps for the
parsing). For the type name (when we use the @type tag), we had the choice between being compliant with the type notation we chose (thus, use a '#') or being compliant with the other tags (where the first word which doesn’t start by a '#' is the name of the element)
We chose the first solution (but this could change).
2) For the @field tag
The @field tag in a @type block is the same
thing than creating a @field block and attaching it to a type thanks to the parent modifier.
The two different notations are equivalent:
------------------------------------------------------------------------------
-- short description.
--
long description
-- @type #recordtypename
-- @field #typeref fieldname description
local t = {fieldname = 'foo'}
Or :
------------------------------------------------------------------------------
-- short description.
-- long description
-- @type #recordtypename
local t = {}
------------------------------------------------------------------------------
-- description.
-- @field[parent =#recordtypename] #typeref fieldname
t.fieldname = 'foo'
For the content assist (ctrl-space) problem, I retested it and it seems to work. In your PCRE flags snippet, you made a mistake: @type PcreFlags should be @type #PcreFlags ; as I said in 1) perhaps we should change this.
3) For the enum
We don’t really have support for enums (as we want to be as close as possible from Lua)
It is still possible to
express enums like this :
------------------------------------------------------------------------------
-- The PCRE flags
-- @type #PcreFlags
-- @field #number PCRE_EXTENDED
-- @field #number PCRE_MULTILINE
-- @field #number PCRE_CASELESS
------------------------------------------------------------------------------
-- A function to compile a PCRE regex pattern
-- @function [parent=#regex] new
-- @param #string pattern
-- @param #number flags
-- @return #userdata The compiled regex object
-- @return #nil, #string Returns nil and error string on failure
Or like this :
------------------------------------------------------------------------------
-- The PCRE flags
-- @type #PcreFlags
-- @field #PcreFlag PCRE_EXTENDED
-- @field #PcreFlag PCRE_MULTILINE
-- @field #PcreFlag PCRE_CASELESS
------------------------------------------------------------------------------
-- A function to compile a PCRE regex pattern
-- @function [parent=#regex] new
-- @param #string pattern
-- @param #PcreFlag flags
-- @return #userdata The compiled regex object
-- @return #nil, #string Returns nil and error string on failure
At the moment, the parameter type is not used by the IDE so it is just here for documentation purposes.
Now that you created your PcreFlags type, you need to define how it could be accessed. There are 3 solutions:
* A global variable preloaded by your VM, so you need to add this to the global.lua file :
------------------------------------------------------------------------------
-- description.
-- @field[parent =#global] regex#PcreFlags PcreFlags
* A field in your module (in regex.lua)
------------------------------------------------------------------------------
-- description.
-- @field[parent =#regex] #PcreFlags PcreFlags
* Indicate that your module modifies the global environment when it is loaded, by adding this in your module (regex.lua)
------------------------------------------------------------------------------
-- description.
-- @field[parent =#global] #PcreFlags
PcreFlags
This last solution is not supported by content assist (ctrl-space) for now, and we thought that a module should modify the global environment as less as possible.
4) return values
You can have as many @return tags as you want
for a function.
The first one is used for type inference, and the others are just for documentation.
It seems you use it well, then.
Hope this helps! ;)
