Re: Doxygen all the things!
Posted: Tue Mar 06, 2012 7:46 am
I just wrote up Doxygen for hsThread as an example that might be useful for people: hsThread.h
I think the standard practice is to keep the function comments in the .h file, so that anyone has a fairly-full API reference just by opening the .h file in an editor.
As for the Pch.h files, those are precompiled headers. They're used to slightly improve compile time of certain modules. In practice, they make it confusing to add more header dependencies and can sometimes result in weird bugs if the compiler doesn't detect that the header should have been recompiled. They also have the side effect of making it impossible to reference one class from a module without including the entire module.
We've been slowly stripping them out in the H'uru fork as we reorganize code, since it makes it much easier to handle header dependencies.
I'd also suggest that CoreLib and plUruLauncher are poor places to start Doxygen work. plUruLauncher doesn't have any classes, it's all static C functions. CoreLib has a few classes (hsBitVector, hsStream, hsGeometry, etc.) that would be good to document, but things like typedefs can probably be ignored. In the case of H'uru, we've refactored a lot of the CoreLib headers to remove old typedefs and defines, and make it 64-bit capable.
I think the standard practice is to keep the function comments in the .h file, so that anyone has a fairly-full API reference just by opening the .h file in an editor.
As for the Pch.h files, those are precompiled headers. They're used to slightly improve compile time of certain modules. In practice, they make it confusing to add more header dependencies and can sometimes result in weird bugs if the compiler doesn't detect that the header should have been recompiled. They also have the side effect of making it impossible to reference one class from a module without including the entire module.
We've been slowly stripping them out in the H'uru fork as we reorganize code, since it makes it much easier to handle header dependencies.
I'd also suggest that CoreLib and plUruLauncher are poor places to start Doxygen work. plUruLauncher doesn't have any classes, it's all static C functions. CoreLib has a few classes (hsBitVector, hsStream, hsGeometry, etc.) that would be good to document, but things like typedefs can probably be ignored. In the case of H'uru, we've refactored a lot of the CoreLib headers to remove old typedefs and defines, and make it 64-bit capable.