#19 Documenting code

[Emanuele Sorce]

I started thinking about contributing to Trigger Rally some month ago, I first tried improving the game physic, but I failed since I haven't got to figure out how to do that and I temporarily gave up.
Now I decided to give it another try, but starting from another prospective: the main problem I faced was that the code wasn't well documented, and it was hard understand what does what where, so I thought to first improve the code documentation, especially of the physic engine related code.
I attach a patch with improved comments, I hope you like it.

[Onsemeliot]

Great. Thank you very much for making the effort to document the code. Maybe this even leads you the solution for the physics engine you tried to come up with already. Unfortunately I'm not the best person to check your improvements since I can not program - at least not with C. But I hope Andrei will be willing to help here.

[Andrei]

[...] the main problem I faced was that the code wasn't well documented, and it was hard understand what does what where, so I thought to first improve the code documentation [...]

I too wanted to do that when I joined the project, but it was too difficult so I abandoned the idea. If you have patience for doing this I will happily accept your patches, maybe we'll even give you Developer privileges so you can push directly to SVN.

As for your physics patches, I personally considered the "basic" patches a bit better than the Bullet remake (from what I tested).

EDIT: I apologize for my confusion, I misremembered you to be the same person as Farrer:

https://github.com/farrer/trigger-rally-bullet

[Emanuele Sorce]

I documented let's say ~79% of the code related to physic. (All the code in the /src/PSim, the code around that manages vehicles and rigid bodies behaviour). I only haven't yet get to understand part of the code (the other ~21%) inside the function that simulate vehicle suspensions, part of the interactions of the wheel with the ground, but I plan to do that. I have some day off now, so I'll finalize it in ~a week. I attach the .patch file here, so you can examine it and merge if you like, would be also great know if you have any suggestion related to the style or to the content of my comments. I hope to be helpful

[Andrei]

Emanuele would you be interested in Developer permissions on this project? That way you can commit your changes directly to our SVN.

[Emanuele Sorce]

This would be surely great!

[Andrei]

Emanuele, you should now be able to push commits to SVN. Let me know if you have problems or questions.

As for the changes you'll make, I have only one request: do not commit unfinished changes.

This means that each new revision must be buildable as-is. In other words, you should never intentionally commit an "intermediary" revision where the code cannot be built and the game cannot run.

[Onsemeliot]

Great. Thank you both for your valuable help. You might have noticed that I didn't commit much recently. This schould change again but at the moment I have a lot of work on my plate.

[Emanuele Sorce]

thank you!