Doxygen all the things!

Discussions About CyanWorlds.com Engine Client & Plugin
Paradox
Member
Posts: 14
Joined: Sun Jul 10, 2011 10:37 pm

Re: Doxygen all the things!

Post by Paradox » 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.

User avatar
Luna
Member
Posts: 11
Joined: Sat Apr 09, 2011 2:37 pm

Re: Doxygen all the things!

Post by Luna » Tue Mar 06, 2012 9:17 am

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.

User avatar
Lyrositor
Member
Posts: 156
Joined: Sun Feb 05, 2012 10:58 pm
Contact:

Re: Doxygen all the things!

Post by Lyrositor » Tue Mar 06, 2012 1:55 pm

@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.
Lyrositor
Explorer #16601888
To D'ni, or not to D'ni. There is no question.
Image

User avatar
Luna
Member
Posts: 11
Joined: Sat Apr 09, 2011 2:37 pm

Re: Doxygen all the things!

Post by Luna » Tue Mar 06, 2012 2:09 pm

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

User avatar
Lyrositor
Member
Posts: 156
Joined: Sun Feb 05, 2012 10:58 pm
Contact:

Re: Doxygen all the things!

Post by Lyrositor » Tue Mar 06, 2012 2:30 pm

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.
Lyrositor
Explorer #16601888
To D'ni, or not to D'ni. There is no question.
Image

Post Reply

Return to “CyanWorlds.com Engine - Client & Plugin”

Who is online

Users browsing this forum: No registered users and 1 guest