Show return table fields

[fabtjar]

https://github.com/astrochili/defold-vscode-guide/blob/master/.defold_api/system.lua#L60

---Returns a table with engine information.
---@return table table with engine information in the following fields:
function sys.get_engine_info() end

https://defold.com/ref/beta/sys/#sys.get_engine_info

This is missing the version, version_sha1 and is_debug fields. Looks like other docstrings are too.

I'm not sure of the best way to format these extra fields when they do get added in.

[astrochili]

It's possible by adding a new @class engine_info to the base.lua file like the url example. I think.

But it's also useful to understand how to fix this in the original documentation from which this one is generated. Now we have a set of some patches, for which thank you, but how not to lose them after the update...

[astrochili]

Now it's possible by adding new classes to known_classes:

config.known_classes = {
    ....
    sys_info = {
        system_name = 'string',
        ...
    }

And adding corresponding param_type_replacements:

config.param_type_replacements = {
    ...
    {
        element_name = 'sys.get_sys_info'
        original = 'table',
        replacement = 'sys_info',
    }
}

[fabtjar]

Nice looks good! I will try to get my issues sorted in the Defold repo first from now on 👍

Is the only reason items will be in config.known_classes and config.param_type_replacements is because docstring need updating on the Defold side?

[astrochili]

Using config.param_type_replacements is required to replace table with sys_info. This can also be fixed in the original documentation, but I don't know if this is okay, such a thing is better to ask the Defold team 🤷‍♂️.

But using config.known_classes is necessary, as I'm not sure if Defold documentation's json format is able to provide useful and stable information about returned tables structure.

Now the structure of the return table is written in the function description as plain text. Somewhere it's there, somewhere it's not, but it doesn't look like a some kind of protocol that we can rely on. I'm not sure that parsing of the plain comments is a good and stable way to create the table structures. That's why I think it's easier to just add the class to known_classes for now.

[astrochili]

But if Defold defines some protocol that describes the structure of the returned tables as an additional object in the documentation structure rather than in plain description, then of course parsing this meta information would be the obvious solution.

[astrochili]

Looked carefully at the documentation, thought again, it might make sense to parse it.

At the moment output format included to the description of the return value looks like this:

---@return table ${CLASS_NAME} table with ${SOMETHING} in the following fields:
---
---${PARAM_NAME_1}
---${PARAM_TYPE_1} ${PARAM_DESCRIPTION_1}
---${PARAM_NAME_2}
---${PARAM_TYPE_2} ${PARAM_DESCRIPTION_2}
---${PARAM_NAME_3}
---${PARAM_TYPE_3} ${PARAM_DESCRIPTION_3}

It may not be a protocol yet, but it is something 🤔 I'll try to implement it someday.

[astrochili]

Updated the release 1.7.0.
Manually added all table types that I found. I hope there are not too many errors.

Feel free to touch if I missed something.

[astrochili]

For the future: it's impossible to parse the table structure from the documentation because it's not a protocol. It looks more like just copy-paste with one style.