Why WAS Torque3D documentation so poor?

#401 @JANR - I just sent out a large e-mail containing all the issues we have discovered to the development team. Some of these are blockers for the doc team, other issues are definitely related to usability. Some of this stuff has been around for years, but buried deep in parts of the engine that have been deemed "stable" and never looked at again.

#402 Documented fields, functions, classes, and callbacks for the following classes (WIP, as some of the classes need to change a little to support the docs):

- Message
- MessageVector
- MessageForwarder
- ForestWindEmitter
- InteriorInstance (not fun)
- LightBase
- LightAnimData
- LightDescription
- HTTPObject
- LevelInfo
- ProjectileData
- PhysicalZone
- ScriptObject
- ScriptMsgListener

This is in the latest CHM, uploaded about 5 min ago. I'm flushing the site cache so you may not see it immediately. Some classes are using a few weird function calls, making it difficult to fully complete them for today's push. Still, just a show of progress.

If you are interested in the full doc update, you can read it here: 7/26/2010 Documentation Update

#403

ALL IMPORTANT NOTE

We've managed to isolate a large list of classes/objects that are meant for internal use or editors. When it comes to developing a game, these are objects you cannot or should not be using. On the engine side, quite a few are going to be either deprecated, hidden from TorqueScript, rewritten, etc.

I'm posting this list now so you can see what will not be in the major doc release. If you see anything on this list worth disputing, please do so ASAP. Something that might change in another release is a special grouping for editor objects that could be extended, but most likely via a tutorial.

KEY
E - Editor class, not meant to be used in your game's development. These are dedicated to the Torque 3D Editors. These may eventually be further abstracted, but in general should not be touched. Good example: GuiRiverEditorCtrl.

X - Internal classes never intended to be modified, classes to be deprecated soon, or classes that exist solely to benefit another SimObject.

Class List
X CachedInterfaceExampleComponent
E CameraBookmark
X CompoundUndoAction
X ConnectionMessageEvent
X ConsoleClassObject
X ConsoleFieldObject
X ConsoleFunctionObject
X ConsoleMethodObject
X ConsoleReflectionObject
E CreatorTree
E DBDeleteUndoAction
E DbgFileView
E DBRetargetUndoAction
E DICreateUndoAction
E DIDeleteUndoAction
X DynamicConsoleMethodComponent
E EditManager
E EditorIconRegistry
E EventManager
E FieldBrushObject
X FileChunkEvent
X FileDownloadRequestEvent
X ForcedMaterialMeshMgr
E ForestBrush
E ForestBrushElement
E ForestBrushTool
E ForestEditorCtrl
E ForestItemData
E ForestSelectionTool
E ForestTool
X GhostAlwaysObjectEvent
E Gizmo
E GizmoProfile
E GuiColorPickerCtrl
E GuiConsoleEditCtrl
E GuiConsoleTextCtrl
E GuiConvexEditorCtrl
E GuiDecalEditorCtrl
E GuiEaseViewCtrl
E GuiEditCtrl
E GuiEditorRuler
E GuiGradientCtrl
E GuiInspector
E GuiInspectorCustomField
E GuiInspectorDatablockField
E GuiInspectorDynamicField
E GuiInspectorDynamicGroup
E GuiInspectorField
E GuiInspectorGroup
E GuiInspectorTypeBitMask32
E GuiInspectorTypeBitMask32Helper
E GuiInspectorTypeCheckBox
E GuiInspectorTypeColor
E GuiInspectorTypeColorF
E GuiInspectorTypeColorI
E GuiInspectorTypeCommand
E GuiInspectorTypeCubemapName
E GuiInspectorTypeEaseF
E GuiInspectorTypeEnum
E GuiInspectorTypeFileName
E GuiInspectorTypeGuiProfile
E GuiInspectorTypeImageFileName
E GuiInspectorTypeMaterialName
E GuiInspectorTypeMenuBase
E GuiInspectorTypeName
E GuiInspectorTypePrefabFilename
E GuiInspectorTypeRectUV
E GuiInspectorTypeS32
E GuiInspectorTypeSFXAmbienceName
E GuiInspectorTypeSFXDescriptionName
E GuiInspectorTypeSFXEnvironmentName
E GuiInspectorTypeSFXParameterName
E GuiInspectorTypeSFXSourceName
E GuiInspectorTypeSFXStateName
E GuiInspectorTypeSFXTrackName
E GuiInspectorTypeTerrainMaterialIndex
E GuiInspectorTypeTerrainMaterialName
E GuiInspectorVariableField
E GuiInspectorVariableGroup
E GuiMaterialCtrl
E GuiMaterialPreview
E GuiMeshRoadEditorCtrl
E GuiParticleGraphCtrl
E GuiRiverEditorCtrl
E GuiRoadEditorCtrl
E GuiShapeEdPreview
E GuiTerrPreviewCtrl
E GuiVariableInspector
E InspectorFieldUndoAction
E MECreateUndoAction
E MEDeleteUndoAction
E MenuBar
E MissionAreaEditor
X MoreAdvancedComponent
X PathedInterior
X PathedInteriorData
E PopupMenu
X RemoteCommandEvent
E Settings
X Sim2DAudioEvent
X Sim3DAudioEvent
X SimComponent
X SimDataBlockEvent
X SimPersistSet
X SimpleComponent
X SimResponseCurve
X SimXMLDocument
E TerrainEditor
E TerrainSmoothAction
E UndoAction
E UndoManager
E UndoScriptAction
E WorldEditor
E WorldEditorSelection
E ZipObject

Edit 1 - Removed LangTable from list, seems kind of important for someone who wants to attempt localization

#404 On a related note, what are the chances that the OP could change the thread title to "Why WAS Torque 3D Documentation So Poor?" once we deliver? =)

#405 The Docs are quickly exceeding expectations. Starting to put to shame even $50,000 engines.

I wonder what is in plain for the C'side of the T3D engine docs? What is down the road for the other Torque products documentation?

#406 @Caylo - Thanks for the encouraging words.

Quote:what is in plain for the C'side of the T3D engine docs? What is down the road for the other Torque products documentation?

Excellent questions, which I hope to address later. Right now I have a severe case of tunnel vision on this project. I'm afraid to say what's left and what my deadline is, but it's safe to say the doc writers are in crunch mode...100% bandwidth taken up in finishing this CHM.

#407 Tunnel vision; they have eye glasses that help that.. hehe.

And I am truly enjoying the new docs. Reading tech manuals and documentation is sorta a hobby of mine, actually more a way of life!

I thought I had knowledge before the new Docs, now im learning new tricks every click of the mouse...

#408 I just have to say, the progress on these script docs have been FANTASTIC so far.
Getting a similar level of detail on the C++ side would easily kill the complaints of all but the biggest haters.

#409 Not uploading anything new today, but thought I'd provide a status update:

We are still making good progress on the usable classes in dire need of documentation, but I'm personally encountering some of the dirtier parts of the engine now. Landing on classes without documentation I have never used, and have not seen anyone use in a while...like AIConnection and AIClient. So antiquated and definitely confusing to a new user who stumbles across it.

Getting tough, work is taking its toll on the team, but we see something in the near distance:

#410 And since I like numbers so much. For ConsoleFunctions, ConsoleMethods, addFields, addVariables, and callbacks (formerly Con::executef()):

Prior to documentation push
Around 280 unsorted classes with partial or no documentation.

As of today
Less than a hundred, many of which have partial docs attached.

#411 In player class reference

drag = 1.3;
maxdrag = 0.4;

#412 @All - Next release of the manual is on Monday.

#413 Sweet. Looking forward to it Mich.

#414 Greetings from the doc team at 3:00am. We are entering the final set of classes to document. It's nice to finally see the list of UNDOCUMENTED shrink down to a small handful.

There are a few classes we have been on the fence about using the @internal flag on. For those of you unfamiliar with Doxygen tags, @internal is used to mark a class/variable/function/etc as something meant for internal use only. When another flag is set, all @internal objects are hidden from the final docs.

It was pretty easy to identify most of these, but we got into situations where we actually had to take a hard look at the code and discuss certain modules. There are classes that seem to function, but no longer have a true use in Torque 3D. Those are marked @internal, with the intention of being deprecated.

Example: VehicleBlocker. Absolutely useless legacy class from the Tribes 2 days that manages to survive TGE, TSE, TGEA, and now Torque 3D. It is most definitely on the cutting room floor.

Other classes are certainly more useful, but have some busted elements to them. They are bugged, and their importance is currently being weighed.

Example: FileStreamObject. So we have FileObject and FileStreamObject. FileObject is the classic and well loved file I/O object for TorqueScript. FileStreamObject was ported from another engine, and exists to provide the ability to stream data from zip files. Well, that leads to ZipObject, which has not been fully tested and definitely has some bugs identified that break functionality.

This is the really sticky area. Should FileStreamObject exist? Should FileObject and FileStreamObject be merged? Since ZipObject works, albeit rarely used, how do we go about writing docs for something that does not fully work and could be deprecated?

With an intense deadline and an overworked team, we have to make some decisions that could easily be overruled by the dev team or the community. With each "iffy" decision like this, I am logging Jira tickets. Tickets for known bugs, requests for clarification, requests for code cleanup, and notification that the writers feel a class should be deprecated or merged.

We've hit pretty much every high priority and stable class (functions, variables, and callbacks included). We are down to this handful of misfit modules devs have not touched since the beginning of Torque 3D, with the exception of porting rendering code to the GFX system.

So when this update goes out tomorrow, I can't expect everyone to scour it. IT IS HUGE. However, if you discover something slipped through as undocumented or find a class missing you use often, please post about it. The doc team can't afford to waste time on something that is broken or planned to be deprecated, but we also do not want to make all the calls about the engine's development.

It's a fine line, and we are open to the idea of being wrong. Just keep in mind that we are using @internal, and not willingly trying to hide stuff we "didn't have time to document." We set aside time to hit everything, but if time can be saved by not documenting something that could change or not be used, well...huzzah!

So, back to work. Thinking this will be the first time since Full Sail where I do not go to sleep for the sake of work. Kind of exciting, got my second wind, coffee brewing, and a milestone in the history of Torque is about to be accomplished.

When you read this, give it up for the doc team (not just me) for this monumental effort to give you all what you have been requesting for years.

#415 Completely unrelated: Huzzah for breaking the 4,000 mark on my post count =)

Still a long way from Garney status, but I'm getting there.

#416 [paraphrazed-quote]
this will be the first time since Full Sail where I do not go to sleep for the sake of work. Kind of exciting, got my second wind, coffee brewing, pixies dancing before my eyes...
[/paraphrazed-quote]

Go docs team!

Quote:
Absolutely useless legacy class from the Tribes 2 days that manages to survive TGE, TSE, TGEA, and now Torque 3D

I reckoned that there might be quite a bit of stuff that had been hiding in there for the last 8 years without any good reason ...

#417 This is like finding burried treasure! If I were a pirate, I'd give a big Aaaaaarrrrrr - I'll leave that for Stickman :)

This is great news, looking forward to all the docs. I don't envy you on the code that has historically been there, working on an incomplete feature must be a bit of a headache.

#418 Wonderful commitment! Thanks a lot guys!!!

#419 Great work! :salute:

#420 Props to Mich and Dave for plowing through this huge task like that.