Page 2 of 2

Re: Doxygen all the things!

Posted: Tue Mar 06, 2012 7:46 am
by Paradox
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.

Re: Doxygen all the things!

Posted: Tue Mar 06, 2012 9:17 am
by Luna
I think FeatureLib might be a good place to start, most of it is already cross-platform safe (https://docs.google.com/spreadsheet/ccc ... xUEE#gid=0) and it contains the console classes where people running their own servers will be interested in.These are already somewhat documented in the code, but not yet doxygen ready.

Re: Doxygen all the things!

Posted: Tue Mar 06, 2012 1:55 pm
by Lyrositor
@Paradox: Do you mind if I implement your documentation in mine (it's a lot better than what I would do...)?
@Luna: Thanks for the suggestion! I'll start work on that instead.

Re: Doxygen all the things!

Posted: Tue Mar 06, 2012 2:09 pm
by Luna
@Lyrositor : fyi I have started on pfConsoleCommandsNet.cpp as it is the file I am most familiar with it (probably the only file I am familiar with in the whole project >.>)

Re: Doxygen all the things!

Posted: Tue Mar 06, 2012 2:30 pm
by Lyrositor
I'll be doing it alphabetically (I like being systematic about my approach to huge projects) but I'll remember to skip that file.
EDIT: After looking into a few files, I think I'm way over my head here. I don't have the programming knowledge, nor the understanding of Plasma, to work on something of this magnitude. I think I'm going to have to give up documenting the actual code in favor of documenting something else. Sorry.