ToME: the Tales of Maj'Eyal

I spent the last weeks and months digging into Lua, the t-engine and module development. After all this time I think I finally get the hang of it. Personally I think that an engine mostly coded in Lua is in theory quite flexible and easy to extent but also really hard to learn.

As a newbie I often have to face some difficult questions when looking at the engine. For example:

1. Where does this variable come from?
Since you can define, add and delete variables basically anywhere in Lua I find it really hard to figure out what variables a function expects. There are some nice comments that explain basic function parameters but as soon as a parameter contains a table it basically is a guessing game which variables have to be in the table.

2. Where does this function come from?
Basically the same problem but with the increased difficulty of interfaces and class inheritance. I often have to search through several classes, interfaces and files to find the right function that I am looking for.

This topic is not meant as a complaint. It think these are the problems you have to face when using a language like Lua but it makes me wonder if there are suitable tools that are helpful. So, my basic questions is: what kind of tools, if any, do you use to understand class hierarchies or expected table variables better? I am currently using a plain text editor and "grep" to search for strings but I think I could do better.

I use Notepad++. I believe Vim is better, as I think it can parse most of the codebase, which allows for extra functionality, but it probably takes longer to set up.
(My examples below are about the ToME4 module, but its similar and actually easier for just engine stuff. I have to check in the module and engine files at times. You'll just need to check the engine.)

1: No easy answer for this one. Checking the function comments and then the function if needed is all you can do here.

2: Since functions are all called inside a directory style framework, you can usually work this out by checking how the function was called.
For example target:combatArmorHardiness(): You should know what type of object target is. Its an actor. So normally, you would check Actor.lua. However we have the extra hint here of "combat" in the function name, which is a cluebat to check Combat.lua instead.
I usually end up searching for the function anyway, as it quickly gets me the function description and definition. If I don't already know what the variables should be, I want to make sure this function does what I want anyway.
A way to speed up function finding is to tweak what you search for. Searching for "_M:getTalentCooldown" instead of "getTalentCooldown" will only find the function definition and a comment in timed_effects\mental.lua about it.
This doesn't always work though, such as for damDesc. This is because it is a terrible local function that is redefined in multiple places and then inherited by talent table files.

Vim may be able to make the above issues easier, but in the end you just need experience with the engine.
As for getting experience. I spent a lot of time asking people on the IRC channel, including DarkGod, as to why my code wasn't working, and how to do certain things.

One extra suggestion: If you start to feel a bit burnt out over your module, maybe take a break and try making a small addon for ToME. This might let you see how the engine works from a different perspective.