01-06-2004 01:07									#1
	PROJECT: Code documentation Support Apolyton, buy GURPS/ Alpha Centauri

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?

	01-06-2004 01:47									#2
	Support Apolyton, buy GURPS/ Alpha Centauri

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

	01-06-2004 02:15									#3
	Enter the AD-FREE zone

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.

	01-06-2004 02:19									#4
	Support Apolyton

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.

	01-06-2004 02:37									#5
	Remove this text

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.

	01-06-2004 02:56									#6
	Support Apolyton, buy Galactic Civilizations: Deluxe Edition

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

	01-06-2004 03:09									#7
	Support Apolyton, buy Galactic Civilizations

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.

Attachment: scheduler.zip
This has been downloaded 11 time(s).

	01-06-2004 03:36									#8
	Get a bigger avatar today!

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.

	01-06-2004 04:21									#9
	Get a bigger avatar today!

quote: 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

	01-06-2004 04:50									#10
	Increase Your PM Length

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.

	01-06-2004 17:30									#11
	Support Apolyton

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.

	02-06-2004 04:21									#12
	Support Apolyton, buy Galactic Civilizations

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

	17-08-2004 02:55									#13
	Got spare money?

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...

Attachment: ctp2_dev.pdf
This has been downloaded 39 time(s).

	17-08-2004 20:50									#14
	Support Apolyton, buy Civilization 2

Great work!

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

	25-10-2004 00:00									#15
	Got spare money?

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.
  

Attachment: ctp2_dev.pdf
This has been downloaded 21 time(s).

	30-12-2004 01:26									#16
	Inflate your Upload Space

Hello,

Is there a documentation somewhere of which directory does what and what file does what?
I have been looking for the exploration code to help me design my own exploration algorithm in Clash and I don't get anywhere. There are robot and robotcom directories for instance, whose names are quite meaningless to me. The variable I was looking for is, of course, public, so I am stuck into grepping all instances of m_pos in the code if I want to go anywhere. I can't understand how you manage to work without a documentation describing what directory stands for what at the very least (well, I can understand, but I know that's not practical). Has anyone done something like listing the directories and explaining what the files inside did, or done some rough architecture overview which would explain more or less which parts of the code are where and how they fit and communicate together?