PROJECT: Code documentation

[vovan]

I apologize if this info is readily available somewhere, but I haven't been up to speed on the progress of the project, so I figured I'd ask in a separate thread.

So, as you probably know from the other thread, I got the game to compile on Visual Studio.NET. I also found that I gave my CtP2 cd to a friend of mine, and so I should have it back... some time soon. Till then, I cannot really test whether the code really works or not. It currently runs, and doesn't complain about missing libraries or anything. Of course, it crashes on startup, which should be caused by missing resources, but who knows. Maybe there's another problem somwhere...

Any way, in the mean time, I decide to read through some of the code to figure out how some stuff works (I am mostly interested in the AI, and graphics, but other stuff is pretty cool too). Well, what can I say?

So, I was wondering. I remember people wanted to document the code some. I was wondering how the progress on that is. Is there any code to download that has been already documented? Or did the effort kinda die out and people are mostly fixing bugs?

[Martin Gühmann]

The altered source file thread contains code to download, we posted every change we made in file form there. From time to time I posted a *.zip with all the files. Here is the according post.. Well it is now more then a month sice when I posted the last pack, so looks like I have to post an update this weak. We use the preprocessor symbol ACTIVISION_ORIGINAL to mark our alterations. I also suggest to mark all the changes that doesn't harm compilation under VC++ 6 made for VC++ 7. Like the typename issure. Well I hope that it doesn't harm VC++ 6, but as adding the keyword typename is standart conform in comparision of leaving it out this should be no problem.

For documentation issures, we just commented the code we were working on, if at all. But this isn't actual a big deal for us, as I know for what I have to look for if I search something in particular.

For instance if I want to look for something like stealing an advance from a captured city I started from the entry in the const.txt, searched the according flag in the source code, found it, searched for the according function that returns this value, found it and finally searched for the place at that it is used.

Well to figure out how to add Slic Database access was a little bit more complicated.

-Martin

[vovan]

Yes, I have seen the code changes thread, and downloaded the last complete update - that's where I got the mss system from any way.

So, as I understand then, there really is no organized code documentation effort. I wonder if it would be useful to document the code? I mean, for fixing bugs it's no big deal, I suppose, but what if the changes one wanted to implement were much bigger? It seems to me that the code documentation would help a great deal then.

[Keygen]

vovan, I am in the process to start a thread about documenting the code but since it needs some preliminary work to be done before I post it and while I am packing stuff as I am moving to a new house at the end of the week it will take me some time before I do that.

[vovan]

That's fine. I'm in no hurry. It's just that while waiting to get back my CD, I thought I'd do something else, since I cannot test out the code. Doing some documentation seemed like a good idea, since I can tell from looking at the functions what they are doing... For the most part. Although I didn't want to be doing any duplicate work, hence the posting of this thread.

But that's okay, I can wait till you post that new documentation thread, and then we'll see.

[Martin Gühmann]

Well I would faviour a ducumention added to the source file. A tool like Doxygen would produce nice html output from the source, unfortunatly the comments we added aren't in Doxygen format.

-Martin

[Peter Triggs]

About a week ago I decided to (once again) try to make sense of the scheduling process. To start with I just copied and pasted Richard Meyers' comments from Scheduler.txt and started adding a few of my own. Eventually, it dawned on me that a systematic approach, using a standard format like Fromafar's, is required so I've got to go back and tidy things up. But for what it's worth here's how I've messed up scheduler.cpp. I've also been working on CTPAgent, CTPGoal, Goal, and Plan.

[vovan]

That's a start. I played around some with the graphics code, and documented some of it. I don't know about Fromafar's style of commenting, but I used Javadoc style:

/**
* Description goes here.
*/
void someFunc() {...}

Because it is understood by Doxygen, and that's what I normally use to generate docs for my own projects.

[Keygen]

Originally posted by vovan

That's fine. I'm in no hurry. It's just that while waiting to get back my CD, I thought I'd do something else, since I cannot test out the code. Doing some documentation seemed like a good idea, since I can tell from looking at the functions what they are doing... For the most part. Although I didn't want to be doing any duplicate work, hence the posting of this thread.

But that's okay, I can wait till you post that new documentation thread, and then we'll see.

There's no need to wait. Do some documentation and post it altogether in the new thread. I am currently doing the same thing in several areas, gathering information in a text file and when will be ready I'll post

[vovan]

Oh, I was thinking you were going to post some organizational details and such. Like maybe a common commenting format that it would be good to follow, and such. I am currently going through some code any way and commenting, so my progress isn't much slowed down by the "wait" any way.

[Keygen]

vovan, regarding the commenting format have a look at this old thread about coding conventions and standards. We didn't come into a common accepting format so it could be a good idea to revive the discussion.

[The Big Mc]

vovan You like doing graphics i could do with a hand integrating some new sea terrains into ctp2.

[ctplinuxfan]

O.k., here's a kind of getting started guide, so perhaps this is a bit off topic.
I started on the #defined macros affecting the build and the build system, but that's far far far from complete...

I will post the documentation source to the Altered source files thread ahead with a started aui_sdl implementation... (so long, there's no SDL configuration as in the doc...)

I'm not happy with the html output yet; latex2html generates garbage output and tex4ht does not like the \maketitle command...

To make it on-topic again: i think that doxygen can produce tex output, so perhaps .tex files generated by doxygen can be \included into the main documentation?

Enough said, here's the pdf...

[Flinx]

Great work!

Just enough information to make me think I might know what I am going

[ctplinuxfan]

Here is an update on the documentation (sources posted on Altered source files thread)

Changes:

• notes on spaces in path problem
• refers to latest ALL patch of 2004-09-13.