Why WAS Torque3D documentation so poor?

#421 I use many of the seemingly useless leftover functions, in my own creatively bent and twisted fashion. I would not expect to see them documented, or even updated along with the rest of the code. But to completely remove them would force recreation of the wheel for the few who find them practical and education as learning examples. There must be some way to simply leave them behind, without complete culling from the code base.

And of course its probably way to late a time to even bother with changing a convention already under exercise on such topic.

#422 @Caylo - If something will be deprecated, we will certainly mark it ahead of time. You can already see where I'm commenting on possible deprecation if you have access to the source.

I could even generate a list of these from the doc system, so we can post about it and gather feedback. For this doc release, nothing has been completely removed except dead variables and dead functions.

#423 For my situation, going back and reimplementing some 'creative' use of removed deprecated code is not a big concern or hassle. I just wanted to state how much of the old 'lost' code still have valuable usage as example code, even some of the stuff that have been busted for as long as I can remember.

This, in reality, is the most minor of issues because in the end Torque users will be forced to evolve along with the engines(as it should be).

#424 Good Job Doc Team. ;)

This is good news indeed. Good luck on all that old code removal.

As for the deprecated code, I am for a lot of old stuff being removed or merged. As for the function FileStreamObject, it sounds like it would be nice to merge it with the FileObject function. I'd suggest merging functions like these and adding an extra argument to the function to enable the option of the old function features.

I.E. (as i'm not sure what the parameters are for this function, this is just a guess, and assuming that a function has such arguments):

FileObject(File, Type, StreamObject);

Where streamobject would be a parameter for running the old FileStreamObject code. Of course this kind of thing would only work if FileStreamObject had similar, if not the exact, parameters of FileObject.

My two cents is, If you can salvage code that isn't wasting resources too much and can be kept alive in ways such as the example above, keep it. If it's too much of a pain or it's a resource hog, lob it off.

#425 To alleviate any confusion, a new version of the docs did not go up yesterday. I had a medical emergency to take care of and had to bolt suddenly, leaving the team hanging. I'm back to work now and will be posting the update today.

#426 I have an example of old and partially 'unworking' bit of code: the splashring effect when a projectile hits water. It's missing the relevant render ring functions in the c-code but the parts in which you can assign particle effects & explosion to it still works. James gave me a few pointers on getting this working last year but since the particle alignment resource was added at about the same time it was felt that it (particle alignment) looked better than the rendered splash ring so the working render code was never added.

I was just curious how you would (or have?) document something like this? Maybe I could even dig up the working render code from last year and see if it still works... that is if by some chance the splash fx is considered obsolete code?

#427 @Michael Perry: I hope your medical emergency was not related to how hard and long you have been working on the Doc's. Course now you can say "I worked myself into the emergency room for that Documentation!"

#428 Yeah, getting the docs out one or two days earlier is not worth any medical emergency, Mich. Take it easy. Everyone knows we're close. We still need you to do more of the docs for 1.1 final! :)

#429 I really appreciate the concern, but I wasn't the one admitted. I've worked worse hours on worse projects. Let's leave it at that.

More docs coming shortly.

#430 Updated title to "Why WAS Torque3D documentation so poor?" from "Why is Torque3D documentation so poor?"

#431 That's awesome.

#432 Thanks Jon =)

If it's ok with everyone...I think I'm going to bed early tonight. It's been one hell of a project and I'm a bit tired:

#433 Must have been sunday michael because those are some "Holie" shorts...waka waka waka

#434 @Ken - Ahaha. So funny I think even these guys would laugh:


Fozzy jokes ftw.

#435 Can anyone point me to the global variables in the documentation? I can't seem to find a lot of them.

#436 They should be associated with the class they were added from, or similar module. Can you list one or two for me so I can track them down?

I'm thinking that maybe instead of grouping global variables with a class, there should just be a page on global variables so it's all in one place. What do you think?

#437 I believe the global variables are all listed in the Namespace List.

#438 Is it possible to use the ConsoleDocClass method on our own components and rebuild the chm docs?

if yes how? It could be very useful that at our level we can implement new comment/example and compile it.

by the way, thanks for the terrific job that was done on this part!

#439
@elvince
Absolutely. Simply document your scripting interfaces the same way as it's done in the stock engine and run Documentation/generateScriptManual.bat to update the docs.

There should also be a document Documentation/internal/engineAPI.rtf that contains documentation about how to write documentation :) If that's not included in the beta drop, let me know and I'll upload it.

#440 That's a great news!!

And I didn't find the rtf, so you can add it to the next beta drop.