Source Code Documentation
by Jon Uhal · in Torque Game Engine · 02/16/2006 (9:18 pm) · 27 replies
I'm going to whine for a second, and I'm expecting to get flamed or pointed in the direction of the dOxygen pile (of you know what) on the garagegames web site, but I'm really wondering when we will see some "useful" source code documentation in the engine code? I've had my TGE license for quite a while now, and even with the release of 1.4, I'm still amazed how little method and variable documentation exists. I know I can go look in the online documentation areas, but there is usually little and more often, no documentation on a particular topic.
Please give me a glimmer of hope that someone at garagegames is working on SOME level of documentation for the engine that everyone purchases. I love the work that is going into the web site and all the new purchaseable items, but I would really like to see some useful documentation for the engine that still confuses me continuously.
Please give me a glimmer of hope that someone at garagegames is working on SOME level of documentation for the engine that everyone purchases. I love the work that is going into the web site and all the new purchaseable items, but I would really like to see some useful documentation for the engine that still confuses me continuously.
About the author
#22
tdn.garagegames.com/wiki/Image:InitializeGame.jpg
02/24/2006 (5:48 pm)
Okay, here is a link to the picture that I drew using Eclipse plugin UMLet. This is more of what I was hoping to see in official documentation.tdn.garagegames.com/wiki/Image:InitializeGame.jpg
#23
02/24/2006 (11:20 pm)
Very cool =) Keep up the good work! 
#24
Awesom Pic. I frequently need to draw diagrams like that(but usually much simpler) but I can never find good software for it. I'm gonna give UMLet a shot right now. Thanks!
02/25/2006 (12:39 pm)
Jon,Awesom Pic. I frequently need to draw diagrams like that(but usually much simpler) but I can never find good software for it. I'm gonna give UMLet a shot right now. Thanks!
#25
The location of the UMLet plugin for Eclipse is:
www.umlet.com
02/25/2006 (2:10 pm)
Thanks. If people like this, I'll definitely keep providing them as I develop more.The location of the UMLet plugin for Eclipse is:
www.umlet.com
#26
Nobody is going to make the engine changes I need for me, and I don't think I'm going to be able to understand what I need to do just by examining the code itself (more documention might make this possible, but there's really no way for me to know.) I -might- be able to 'get it' by simply staring at the code, debugging, etc...but is that really any way to accomplish what I need? I don't think so, so it's just time to buckle down and figure out what classes I need to take.
I guess I'm just a little frustrated. I know the answer is there, somewhere...but I lack the tools (my knowledge) to implement what I see so clearly :( But, only good can come of learning this on my own :) When you can't find answer from somebody else, equip yourself to answer it yourself.
Hopefully, as I get some education under my belt, I can not only accomplish what I want, but contribute back to the community as well.
02/28/2006 (2:23 pm)
I'd like to cast my vote, that the single greatest thing I think would help the Torque community would be in-depth documentation on the code. I suspect there are many out there, who aren't great at linear algebra/matrix/vector math, and who are relatively new to C++. I can "read" the code, but often it simply isn't clear to me what's happening still. I'm convinced that someone in my position has really only one option. Nobody is going to make the engine changes I need for me, and I don't think I'm going to be able to understand what I need to do just by examining the code itself (more documention might make this possible, but there's really no way for me to know.) I -might- be able to 'get it' by simply staring at the code, debugging, etc...but is that really any way to accomplish what I need? I don't think so, so it's just time to buckle down and figure out what classes I need to take.
I guess I'm just a little frustrated. I know the answer is there, somewhere...but I lack the tools (my knowledge) to implement what I see so clearly :( But, only good can come of learning this on my own :) When you can't find answer from somebody else, equip yourself to answer it yourself.
Hopefully, as I get some education under my belt, I can not only accomplish what I want, but contribute back to the community as well.
#27
Nobody is going to make the engine changes I need for me, and I don't think I'm going to be able to understand what I need to do just by examining the code itself (more documention might make this possible, but there's really no way for me to know.) I -might- be able to 'get it' by simply staring at the code, debugging, etc...but is that really any way to accomplish what I need? I don't think so, so it's just time to buckle down and figure out what classes I need to take.
I guess I'm just a little frustrated. I know the answer is there, somewhere...but I lack the tools (my knowledge) to implement what I see so clearly :( But, only good can come of learning this on my own :) When you can't find an from somebody else, equip yourself to answer it yourself.
Hopefully, as I get some education under my belt, I can not only accomplish what I want, but contribute back to the community as well.
02/28/2006 (2:27 pm)
I'd like to cast my vote, that the single greatest thing I think would help the Torque community would be in-depth documentation on the code. I suspect there are many out there, who aren't great at linear algebra/matrix/vector math, and who are relatively new to C++. I can "read" the code, but often it simply isn't clear to me what's happening still. I'm convinced that someone in my position has really only one option. Nobody is going to make the engine changes I need for me, and I don't think I'm going to be able to understand what I need to do just by examining the code itself (more documention might make this possible, but there's really no way for me to know.) I -might- be able to 'get it' by simply staring at the code, debugging, etc...but is that really any way to accomplish what I need? I don't think so, so it's just time to buckle down and figure out what classes I need to take.
I guess I'm just a little frustrated. I know the answer is there, somewhere...but I lack the tools (my knowledge) to implement what I see so clearly :( But, only good can come of learning this on my own :) When you can't find an from somebody else, equip yourself to answer it yourself.
Hopefully, as I get some education under my belt, I can not only accomplish what I want, but contribute back to the community as well.
Associate Matt Fairfax
PopCap
One problem we have is trying to find the right places to focus on at the right time. For example, we pour resources into Getting Started Docs and we start getting slammed for our "lacking" Reference Docs. Or we put time, money, and effort into building an infrastructure that allows the Function Docs to stay up to date with the current source code (Elixir) and we get slammed for not having enough Usage Docs. Arrgh! Down boys! =P
Btw Jon, the Torque Databocks Reference might be handy for you. It doesn't cover everything but, if you start moving parts of it over to TDN, you could help to flesh it out in the areas you find lacking.