search

PhantomGamesDevelopment / Galactic-2D

Open source engine technology created in C++.
1 stars 1 forks source link

Documentation #29

Open Ragora opened 9 years ago

Ragora commented 9 years ago

I recognize that is an early WIP but the in-code documentation is extremely lacking. There are a good handful of methods that are concisely named and there is a small tagline (more or less) describing it, but then it fails to describe other aspects of the function. A good example would be updateThreadStackSize in pThreadContinual.cpp: https://github.com/PhantomGamesDevelopment/Galactic-2D/blob/development/Source/EngineCore/Thread/pThreadContinual.h#L91

Why is it protected? Exactly why is it virtual? What exactly is the purpose of the newSize parameter in the default implementation (especially since it is just passed in by-value, assigned to and returned)?

Doxygen style comments are both easily Human readable and would allow you to generate clean HTML documentation from them. EasyDelegate is a good example: https://github.com/Ragora/EasyDelegate/tree/188e57becfeadc75733717aa2acdfe844a04c298/include

And the accompanying web page: http://ragora.github.io/EasyDelegate/

Phantom139 commented 9 years ago

I see you like making use of the Minor Error tag, it must be that glaring red text that makes it shiny or something, I dunno :)

Anyways, this is something that I really should be spending more time doing, but at the moment I'm more focused on finishing the framework itself. I want to finish at least writing the base code for the Generic platform and the Windows platform before I commit to a full sweep of the codebase for testing runs, etc. But I will make a to-do note to get to this as soon as I get that first test run done.

Ragora commented 9 years ago

I use it for anything that doesn't halt development, which is a lot of things.