Why WAS Torque3D documentation so poor?

#121 I've been here since April 2001. I would be amazed beyond belief if Torque ever got decent docs.

__________
james

#122 @Mich: That's good to know. I've been sticking closer to your updates and stuff since we actually bought the engine. Before that I was looking at a lot of stuff on the graphical side of T3D, simply because our previous engine was a great learning source, and had great API, but not a great renderer, oddly enough I find that Torque was the opposite, heh, no offense intended. I had my fair share of fussing at the head coders on our previous engine. So far I don't see that happening with torque, outside of the area of documentation, because it seems to have a great renderer and can make some great stuff, I'm just waiting for those docs.

Well Mich you gotta fan, keep us posted on those docs, I'm really REALLY looking forward to them. The sad thing is I gotta do a lot of website work before I can dive into Torque T-T so I don't know if I'm gonna make the wait. I just want those docs so bad @.@. I can be patient though...

Good luck guys.

#123

Quote:
The bottom line is that documentation, in the near term, won't teach you how to make games,

hmm is this really the bottom line about the documentation issue? I dont think I got that memo. yes, documentation doesnt teach people how to make games in the near term... nothing does. but documentation helps. in fact, I'd even say documentation is the most helpful thing for a game-making person. as a programmer, Im sure Eric would agree.

Quote:
The big message here is that action speaks louder than words. We've been listening, changes are on the way.

ok, this is getting annoying. yes, actions do speak louder than words, but words DO still speak, and words dont diminish the effectiveness of later actions. in my experience, people tend to favor a special combination of the two, where a person says what theyre going to do, and then actually follows through on schedule. I think I would favor that approach as well.

IMO we're not being given a schedule because we will not be seeing any results of any of the steps that are currently being taken toward getting documentation in the near term. we appreciate the concerted effort, but please stop pretending we're not getting a hard deadline because "actions speak louder than words".

I'm glad I finally have a proper place to vent these kinds of things. =)

again, please add console functions to the CHM file. thanks guys.

#124 ... console functions ...

Remember folks, you can do a dump() on any object/classtype in the editor - also localclientconnection and serverconnection. edit: serverconnection being teh same as gameconnection class

As a source code user I'd welcome a fully furnished API for the engine code.

Quote:
documentation ... won't teach you how to make games

Documentation should be solely concerned with being a reference for the engine and a user manual for the editors and their environments. In other words - how to use the Torque3D software.

#125 yes Steve YorkshireRifles is right. you can call dump() for any console object and see what it can do. but its poorly formatted and not commented adequately.

my previous response was a bit harsh. wheres Novack when you need him? =)

#126

Quote:I'm glad I finally have a proper place to vent these kinds of things.

You are wrong. The forums are most certainly not a place for childish venting and most certainly not a place to go off about a constructive comment like this. You are depleting patience once again.

#127 That was uncalled for...

As for the API they said it will be released, so just be patient.

@Steve: That looks a little bit helpful, but not something I'd use for making a full game. I'd rather get the API, but this is a start. I'll just wait though, full documentation that explains uses for functions and exactly what they do is a little more helpful.

#128 Hey everyone. Here is what has happened so far:

1. Had another meeting with Eric regarding logistics. We decided this was going to be a team effort, which means more than just myself documenting the code. Decision made: anyone not currently locked up will work with me for a while to fill out ConsoleFunctions, ConsoleMethods, and member fields.

2. Tom, Rene, and myself went through a round of debate and analysis of Doxygen vs NaturalDocs. NaturalDocs is winning, but we have a few hours to make the final decision. Our script and engine reference will be generated via NaturalDocs if it's clear. I tested it on a small scale to review formatting options, presentation, and what content is generated.

You can view that here: Test Docs. Specifically, have a look at VectorAdd which is currently the most complete script function reference. The format, presentation, and scheme is not finalized. There are also a couple of spelling errors that will be corrected at the end.

3. Currently, when you call dumpConsoleFunctions() by itself all C++ and script global functions will be spit out to the console. Any usage strings mostly use doxygen tags. This is not useful, readable, or desired. I am rewriting our ConsoleDoc system to handle NaturalDocs, making regeneration of script and engine reference a snap. The same practice will be applied to other dumpXXXX functions. Go go C++ skills.

4. Developers are in the process of volunteering for modules to comment. Whatever is left will be assigned by me to whomever has the lightest load.

Work on this new task started about 24 hours ago.

#129 That's looking pretty good ^^

I may aswell be the first to ask, how long do you think it will take?

#130 @Leon - Not sure. Never worked with this many people on a documentation project. I'm still getting a head count, though. All of them are programmers, which means no ramp up time for them. No one knows the code better than they do, so I'm expecting stellar results.

#131 Well by the looks of those test documents, it will be top notch. Good luck, can't wait for the release!

P.S Disgard the message you got on Sunday ;)

#132 @Sean H. - Dude, seriously, calm down. You have multiple people asking you to settle down and be constructive. You managed it once, then flew off the handle with sarcasm when Steve tried to lend some short-term help by providing us with the dump command. He never said it would replace docs, it was meant to help people out with something that's available now.

@All: I feel the need to clarify my last post, because there are some people who missed the point entirely. When I posted the request to stop whining about what other engines do, what I meant was that GG knows what Unity and UDK are doing, and if they don't, then there are a thousand and one posts on their forums to educate them. Not to mention the internet. I'm positive they have it, and if they're interested, they can go look up whatever it is they want to regarding those engines. A few people on here shouting, "UDK AND UNITY HAVE BETTER DOCS THAN T3D" is not going to influence them one iota. All you're doing is detracting from the thread by filling it up with useless information.

Instead of whining about other engines and how long you've been without docs, you could be providing helpful feedback. If you don't think its your responsibility to "do GG's job for them" then kindly decide not to post and just read. Some of us would like to offer up solutions to help speed documentation creation along because we recognize a wider pool of ideas can help the brainstorming process, thus improving the overall quality of the product being created.

@Michael P. - Awesome! Looks like you guys have a handle on the process and things are really moving along. Thanks!

#133 @Mich: Yea, that's what I was thinking of in terms of full reference. That is very similar to our previous engine's API docs, which were also very thorough. Here is the new version for the new engine. For an example scroll down to Engine Objects and check the stuff there. It was very thorough. I'm thinking the API for T3D might not be as descriptive, but for at least a decent scripter (I'd call myself a scripter rather than programmer, cuz using TS would technically be scripting, and that's all our previous engine was) could just use a simple:

void FunctionName (Vector blah)

Description: it does this...

Returns: it returns this...

Example:
%a = 200;

%b = FunctionName(%a);

Which is what the new docs look like. I'm hoping that should be enough for newbies too, but I'm not sure...When I was a complete newbie I was not very good at looking through such docs, but that's also the "tutorial stage".

Either way Mich, you and the guys seem to be doing a good job. I like the format of the docs. There is just one thing I wanna point out, and I know it sounds crazy but I want to point it out seriously.

Make sure when you use examples to comment the stuff that is not code:

Quote:%a = "1 1 1";
%b = "2 2 2";
%c = vectorAdd(%a, %b); //Value of %c is "3 3 3"

or

Quote:%a = "1 1 1";
%b = "2 2 2";
%c = vectorAdd(%a, %b);
//Value of %c is "3 3 3"

Honestly, I think it would help, it might sound stupid, but believe me...

And one more thing, it might just be a pet peve, but will you guys be putting all the stuff on single pages like that? I would think that each function needs it's own page to avoid confusion. It's fine with me if it isn't but I did find myself looking down to the next function after I had finished reading the first.

#134 Thanks all. I'll keep those points in mind while we start working. Now, we haven't fully dedicated to NaturalDocs. There are a couple of big drawbacks to consider, such as how Torsion parses Javadoc format for its intellisense. We are getting close to a final decision, but we do not want to break the ConsoleDoc and Torsion if we can help it. Rene and Tom are really backing me right now to make sure the right tech is in place. Make sure you give them props too.

#135

Quote:
Work on this new task started about 24 hours ago.

I'm glad you decided to share your plans with us regarding the push for documentation. good to hear this is going somewhere. This looks and sounds really good.

@Tom B. - I'm totally calm now. =)

#136

Quote:
You are wrong. The forums are most certainly not a place for childish venting and most certainly not a place to go off about a constructive comment like this.

you're right Rene. The forums are a place where we can learn, communicate, and share with each other. the most important overriding rule for the forums is to stay on topic, and to not derail the thread. by my venting comment, i mean that usually, when I complain "why is torque3d documentation so poor?" I'm told that I'm derailing the thread and my comments are sometimes deleted. however, it just so happens thats the topic of this thread. thus, my comments about documentation are always on topic here. =)

I'm going to add this thread to my favorites so I can periodically add comments relevant to the topic in the event i feel we're not progressing toward our common goal.

#137 When it comes to the documentation for torquescript, I would highly suggest including a section detailing the sequence of calls used in the mission loading process. this could include an explanation of commandtosever/commandtoclient calls, ghosting, and handling the callbacks. IMO, explaining how a mission gets loaded would be an ideal way of introducing users to the key concepts like the game gui.

everything else in torquescript is pretty basic.

#138 I agree with Sean. I think a tutorial on the main loading sequence would be highly informative to new users.

#139 Something like this?

Torque Connection Sequence Overview
Torque Connection Sequence Diagram

#140 BTW, we also gave SimObject::dump a pass to generate nicer dumps. (Looks sort of garbled on the forum)

Class: SimObject
Static Fields:
  bool canSave = "1"
    Whether the object can be saved out. If false, the object is purely transient in nature.
  bool canSaveDynamicFields = "1"
    True if dynamic fields (added at runtime) should be saved. Defaults to true.
  bool hidden = "0"
    Whether the object is visible.
  bool locked = "0"
    Whether the object can be edited.
  SimObject parentGroup = "RootGroup"
    Group hierarchy parent of the object.
  pid persistentId = ""
    The universally unique identifier for the object.
Dynamic Fields:
Methods:
  void    assignFieldsFrom( SimObject object ) - Copy fields from another object onto this one.  The objects must be of same type. Everything from the object will overwrite what's in this object; extra fields in this object will remain. This includes dynamic fields.
  void    assignPersistentId() - Assign a persistent ID to the object if it does not already have one.
  string  call( string method, string args... ) - Dynamically call a method on an object.
  int     clone() - Create a copy of this object.
  int     deepClone() - Create a copy of this object and all its subobjects.
  void    delete() - Delete and remove the object.
  void    dump() - Dump a description of all fields and methods defined on this object to the console.
  void    dumpClassHierarchy() - Dump the native C++ class hierarchy of this object's C++ class to the console.
  void    dumpGroupHierarchy() - Dump the hierarchy of this object up to RootGroup to the console.
//......
  string  getName() - Get the global name of the object.
  string  getSuperClassNamespace() - Get the name of the superclass namespace assigned to this object.
  int     getType() - Return the type mask for this object.
  bool    isChildOfGroup( SimGroup group ) - Test whether the object belongs directly or indirectly to the given group.
  bool    isEditoryOnly() - Return true if the object is only used by the editor.
  bool    isExpanded() - Get whether the object has been marked as expanded. (in editor)
  bool    isInNamespaceHierarchy( string name ) - Test whether the namespace of this object is a direct or indirect child to the given namespace.
  bool    isMemberOfClass( string className ) - Test whether this object is a member of the specified class.
  bool    isMethod( string methodName ) - Test whether the given method is defined on this object.
  bool    isNameChangeAllowed() - Get whether this object may be renamed.
  bool    isSelected() - Get whether the object has been marked as selected. (in editor)
          onDefineFieldTypes - 
  bool    save( string fileName, bool selectedOnly=false, bool preAppendString = "" ) - Save out the object to the given file.
  int     schedule( float time, string method, string args... ) - Delay an invocation of a method.
  void    setCanSave( bool value=true ) - Set whether the object will be included in saves.
  void    setClassNamespace( string namespace ) - Assign a class namespace to this object.
  void    setEditorOnly( bool value=true ) - Set/clear the editor-only flag on this object.
  void    setFieldType( string fieldName, string type ) - Set the console type code for the given field.
  bool    setFieldValue( string fieldName, string value [, int index ] ) - Set the value of the given field on this object.
  void    setFilename( string fileName ) - Sets the object's file name and path
  void    setHidden( bool value=true ) - Hide/unhide the object.
  void    setInternalName( string newInternalName ) - Set the internal name of the object.
  void    setIsExpanded( bool state ) - Set whether the object has been marked as expanded. (in editor)
  void    setIsSelected( bool state ) - Set whether the object has been marked as selected. (in editor)
  void    setLocked( bool value=true ) - Lock/unlock the object in the editor.
  void    setName( string newName ) - Set the global name of the object.
  void    setNameChangeAllowed( bool value=true ) - Set whether this object can be renamed from its first name.
  void    setSuperClassNamespace( string namespace ) - Assign a superclass namespace to this object.

Of course, these dumps are primarily meant as quick in-engine help from the console and not as substitute for "real" documentation. Still, I'm finding dump() to be a pretty handy method.