Armory/Iron documentation


#1

Hi guys, I’ve recently started trying to implement more complex behaviors on my traits (since so far I’ve been only doing stupid straightforward stuff), while trying to learn the framework in order to eventually contribute. Initially I was trying to implement slerp in Quaternions since it doesn’t seem to exist but I realised that I didn’t know whether the quaternion operations were using degs or rads (I presumed it would be rads but I wanted to know for sure) so I went to the API reference just to find zero information there, no problem I went to the code and tried to figure it out, but then I needed to know what kind of information was the Time package delivering (secs, milisecs, or something even fancier that needs to be converted to ms like in JavaScript), I also wanted to know the difference between Time.time and Time.realTime (same for delta) so again I tried with the documentation just to find no information at all, so I got curious and went through all the other items just to find that, besides the top level elements, the full API is almost completely undocumented, the API reference is no more than a list of functions, no information whatsoever.

Needless to say that this freaked me out, since the entry point not only for contributors but for engine users as well is at least the API reference documentation (you cannot go through 7 years of code from armory and its dependencies every time that you want to know something, on top of that, the code is not really documented either…), I’d like to know if there is already any kind of initiative to document the API reference that simply has not been pushed yet, or this is just the case that armory is fully undocumented and it’s nowhere close to be documented anytime soon. Cheers guys.


#2

There just isn’t a whole lot of documentation at the moment. Armory is changing a lot all the time and Lubos is the only one who has been really working on it for years ( for the Armory specific stuff, not counting Kha ).

I’m pretty sure there isn’t any kind of initiative to document the API. Any help that we can get with that would be great. It isn’t impossible to figure stuff out without the documentation, even though it will definitely be more work. You can always ask on the forums. I have learned a whole lot about the engine as I have contributed and worked on my game with it, and I read pretty much every post on these forums. Also, if you ever figure out an answer to a question or what a function does, you can submit a PR for the API documentation. If I get time I will try to write some function documentation as I go about working on my game, but the more people that contribute the faster it is going to get done.

You could argue that we should focus more on documentation, but at the same time there are major features that people are still asking for that are required just to make a game. There is lots that needs to get done, but we are doing the best we can and Armory continues to get better every day.


#3

Thank you for your answer @zicklag. The problem with going through the code, or needing to ask in forums is the iteration time, specially for basic stuff like knowing what every function does instead of guessing what it does (it might sound stupid but I find that kind of uncertainty very unsettling), you cannot wait few hours until your question gets answered in the forums to know what a function does (I guess discord might be better, but still…) and you can’t always go to the code for the certainty of what every function is doing. In any case I agree with you in that people should make an effort to comment their contributions, and you answered my question about how probable is to have a minimal documented API any time soon. I appreciate it :slight_smile: .