Code Documentation

#21 Tim's idea sounds good to me.

The best place for me would be the GUI editor and the default controls.

For me to work on "one level removed" bits like editors is my way of adding little bits of lint and fuzz to make this tarball less sticky.

Adrian, you going to open this project within GG?

Dave

#22 Sorry I'm late for the party guys... Hope there's still cake and ice cream left...
I emailed the "business@garagegames.com" addy in regards to documentation, prior to stumbling across this thread. In summary, I'm very willing to contribute anything and everything I can to this project. I'm putting the wraps on a UScript API that I did, mainly to familiarize myself with the more extensible aspects of the new WinHelp API (tres chic, by the way...it's become much more than a simple little stack of purple help books with this latest incarnation..)
Regardless, just wanted to throw my name on the pile here. I can do pretty much anything, as far as documentation goes, but I guess I'd be most effective on the distro end of things in this project (me != guru... yet...)

/me waits patiently for something new to keep him up for days...

#23 Sorry been out for the last week. I am still working on the document system, and yes I agree with Tim, that we need docs for more then just the engine. I should have a preview of the system I am working on sometime this week.

#24 VVntrmute:

all my cake and ice cream belong to you

I have to back out of the project for the time being. Fortunately this comes just as a pro with relevant formal experience has popped up.

Dave

#25 In light of Tim Gift's post for doc requirements, I suppose its a good idea to start on the available code. I'm guessing everyone will find Tribes 2 scripts (.cs files) documentation a satisfactory start.

I've already started compiling a list of the Tribes 2 Classes extracted from the script files. Those who read Tim's earlier post on datablocks can recall their connection to T2 Classes, so I've taken the liberty of documenting all the member variables and member functions of each defined datablock. I think I've documented 30% of the datablocks so far (after about 2 hours of work, so I should be done sometime later this week), and until I read this post, I intended to keep the list for my own purposes. If you guys think my list could be of some use, I'll make it public.

Most entries are in this format

eg.
I) Player
1. PlayerData
Member Variables :
-> emap
description: bool, dictates whether or not the player model should be environment mapped
-> class
description: the class PlayerData is associated with (generally "Armor")
-> ...
-> ...
Member Functions :
-> onCollide(%this, %obj, %data)
description: blah blah blah

and so on

Tell me what you think,

--Timothy "Drake" Ford

#26 Maybe you shouldn't document the Tribes2 code itself, rather the scripting language. From what I've heard from GG, the scripting language is the heart and soul of the V12, and very changeable. Going further in my own deduction, no Tribes2 specific code will be left in, I assume this means all the Tribes2 specific scripting language functionality and propriety classes. I have never scripted in Tribes or Tribes2, your understanding of the language would be invaluable to me to teach me syntax, code tricks, etc. Also based on the knowledge of the Tribes2 scripts, you could probably figure out how the scripting language is changeable, and what it's capable of. I think this will help a V12 licensor like myself, rather than how to code for Tribes2.

#27 Timothy,

I myself am very interested in your list. Are you using Perl or something to do that? I am primarily interested for coding mods for T2, but I will most likely be moving on to the V12 soon enough and try to create a game with it (mostly because I want something to show for myself in order to get a scripting / jr. programming job somewhere).

I know that many many people in the T2 community would be interested in such a list... Just check out the forum on tribalwar.com ...

I wouldn't mind helping out some with documenting the scripting language as far as I am able.

Could I get a copy of that list?
jimmyrowley@yahoo.com

Tim,

When you mentioned that the gui and scripting and debugging, etc. code will need documenting, does that mean that those scripts will be left in the V12 engine? I assumed that almost all of the scripts would be removed as part of Tribes2. I guess the tools, etc. are really not game specific so I guess I was mistaken. As for objects adding scripting functionality though, won't that all be removed? On another note, doesn't Dynamix have some sort of class list or something they used in-house? If so, maybe we could help to persuade them to release some of it to the public.

Everyone else,

Finally, I would like to point out to the community here that we are where the onus of documenting the V12 is finally going to have to lie. Like Tim said, the two of them could never have the time to do all of it, and besides, wouldn't we rather have them making the engine better for us rather than sitting around documenting everything? =) I've seen quotes from Tim Sweeney of Epic that the Unreal Engine itself is largely undocumented. Tim wrote some white papers on the scripting language and different technologies involved, but it has been the mod community primarily that has documented the scripting language for them. He has said that they have often pointed their licensees to the mod community web sites in order to help get them up to par. Hell if they can get away with licensing their engine for a quarter million dollars and not document it, then why should GG? If we want to help make this business model work, then I think we will have to be the ones to help each other out for the most part.

#28 /me wipes ice cream and cake crumbs off his face

I think we could start a new phenomenon with that quote...All your cake are belong to us..?
Anyways...
This aforementioned datablock documentation, as well as any of the mentioned efforts to document the T2 scripting language is quite timely...I just got back from the club fo' the evening, and was getting ready to attempt to piece together some sort of passable explanation of these datablocks, etc for the blokes in the TribalWar forum...needless to say, anyone who's able to contribute anything to this modding/scripting/etc movement will be able to help many, many people...
So definitely count me in for people that would love to get a copy of this datablock documentation, most definitely (monkey_of_wrath@hotmail.com)
Anyways...I'm off to work on this little tutorial...

#29 I would like to recommend Doxygen as a source-level documentation tool. I have found it extremely useful - even in a commercial environment - and it's cross platform if that's a requirement :) It can generate HTML, RTF, CHTML, and man pages if you want. It also links to a most excellent graphing tool (DOT from AT&T labs) that makes class diagram and dependancy diagrams. Well worth considering if you do not already have such a tool in mind. Oh yeah - it's free.

See: www.doxygen.org

Cheers,
Stephen

#30 Forgive me for joining the party late, particularly if what follows is already documented elsewhere (pointer anyone ?):

Clearly documenting the code for the V12 engine is going to be important to those of us that license it and, I suspect, to GarageGames as well. If the licensees must expend significant effort to understand the engine as a result of limited documentation then this may impact the adoption of the V12 technology for anything much beyond mods or conversions. It may also trigger a drop in quality as licensees stumble through the code trying to make their own changes and getting it wrong.

Maybe the community of licensees can contribute to that effort in a significant way and thus help each other and GarageGames with what may be a large task. However, before this can happen it seems critical that some form of source repository be established (for example CVS). Without this and the process / controls associated with it I am concerned that we'll witness a never-to-be-undone forking of the technology and a lost opportunity for everyone.

So, after all those words, the reason for this post: where can I find information on how the source for the V12 technology will be managed ? If this isn't yet decided, is there a plan in place to resolve it ?

Thanks in advance,
H.

#31 Well seeing as how the source isn't released yet ... I sort of doubt there is a source repository :)

#32 The fact that the source isn't released yet simply means that there is no *public* repository. I am sure that GarageGames itself will have a source repository.

#33 im no programmer, but i think the best way to get the ball rolling is for GG to set the standards of how the documentation is handled. this way they can ensure that the info is properly disseminated and updated. they shouldnt be the ones to do most of the work, but they should handle the administration of it. that way we dont get the fork in the road as outlined above, and v12 developers know they are getting 'official' documentation.

just my $.02

#34 we will definatly help out once we get v12 and get stuck into it!
good idea guys